Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@backstage/catalog-model

backstage571.4kApache-2.01.7.3TypeScript support: included

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

backstage

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2024 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@backstage/catalog-model

1.7.3

Patch Changes

1.7.3-next.0

Patch Changes

1.7.2

Patch Changes

1.7.2-next.0

Patch Changes

1.7.1

Patch Changes

1.7.0

Minor Changes

  • 74acf06: Add dependencyOf prop to catalog model for Component kind to enable building relationship graphs with both directions using dependsOn and dependencyOf.

Patch Changes

1.6.0

Minor Changes

  • 34fa803: Introduce an optional spec.type attribute on the Domain and System entity kinds

Patch Changes

1.6.0-next.0

Minor Changes

  • 34fa803: Introduce an optional spec.type attribute on the Domain and System entity kinds

Patch Changes

1.5.0

Minor Changes

  • 79025f3: Introduce a domain attribute to the domain entity to allow a hierarchy of domains to exist.

1.5.0-next.0

Minor Changes

  • 79025f3: Introduce a domain attribute to the domain entity to allow a hierarchy of domains to exist.

Patch Changes

1.4.5

Patch Changes

1.4.5-next.0

Patch Changes

1.4.4

Patch Changes

1.4.4-next.0

Patch Changes

1.4.3

Patch Changes

1.4.3-next.0

Patch Changes

1.4.2

Patch Changes

1.4.2-next.2

Patch Changes

1.4.2-next.1

Patch Changes

1.4.2-next.0

Patch Changes

1.4.1

Patch Changes

1.4.1-next.0

Patch Changes

1.4.0

Minor Changes

  • 33eae4b39a95: Deprecate target field and make targetRef required in common.schema.json

Patch Changes

1.4.0-next.1

Patch Changes

1.4.0-next.0

Minor Changes

  • 33eae4b39a95: Deprecate target field and make targetRef required in common.schema.json

Patch Changes

1.3.0

Minor Changes

  • be9c4228073: Modified the regex for DNS label validation to support IDN domains

Patch Changes

1.3.0-next.0

Minor Changes

  • be9c4228073: Modified the regex for DNS label validation to support IDN domains

Patch Changes

1.2.1

Patch Changes

1.2.1-next.1

Patch Changes

1.2.1-next.0

Patch Changes

1.2.0

Minor Changes

  • d51668882d: Adds the tRPC API type to the catalog.

Patch Changes

1.2.0-next.1

Minor Changes

  • d51668882d: Adds the tRPC API type to the catalog.

Patch Changes

1.1.6-next.0

Patch Changes

  • 2518ef5b8a: Add deprecation tag to kubernetes constants in catalog, constants are now defined in plugin-kubernetes-common

1.1.5

Patch Changes

1.1.5-next.1

Patch Changes

1.1.5-next.0

Patch Changes

1.1.4

Patch Changes

1.1.4-next.1

Patch Changes

1.1.4-next.0

Patch Changes

1.1.3

Patch Changes

1.1.3-next.0

Patch Changes

1.1.2

Patch Changes

1.1.2-next.2

Patch Changes

1.1.2-next.1

Patch Changes

1.1.2-next.0

Patch Changes

1.1.1

Patch Changes

1.1.1-next.0

Patch Changes

1.1.0

Minor Changes

  • 4cc81372f8: Introduced GroupDefaultParentEntityPolicy to set a default group entity parent.
  • 1380b389dc: Adding an optional type field to entity links to group and categorize links

Patch Changes

  • c3cfc83af2: Updated JSDoc to be MDX compatible.
  • f9f1de8100: Add shared annotations for Kubernetes clusters
  • f1dcc6f3c6: Added type predicates for all entity types, e.g. isUserEntity
  • 72622d9143: Updated dependency yaml to ^2.0.0.
  • Updated dependencies

1.1.0-next.3

Patch Changes

  • 72622d9143: Updated dependency yaml to ^2.0.0.

1.1.0-next.2

Minor Changes

  • 4cc81372f8: Introduced GroupDefaultParentEntityPolicy to set a default group entity parent.

1.1.0-next.1

Patch Changes

1.1.0-next.0

Minor Changes

  • 1380b389dc: Adding an optional type field to entity links to group and categorize links

Patch Changes

  • c3cfc83af2: Updated JSDoc to be MDX compatible.

1.0.3

Patch Changes

  • 131a99e909: Added targetRef to common.schema.json to match the Typescript type

1.0.3-next.0

Patch Changes

  • 131a99e909: Added targetRef to common.schema.json to match the Typescript type

1.0.2

Patch Changes

1.0.2-next.0

Patch Changes

1.0.1

Patch Changes

  • e0a51384ac: build(deps): bump ajv from 7.0.3 to 8.10.0

  • c12f8374d1: Added a connection between www-artist and artist-lookup components

    <summary>Screenshots</summary>

    www-artist component

    artist-lookup component

1.0.1-next.1

Patch Changes

  • c12f8374d1: Added a connection between www-artist and artist-lookup components

    <summary>Screenshots</summary>

    www-artist component

    artist-lookup component

1.0.1-next.0

Patch Changes

  • e0a51384ac: build(deps): bump ajv from 7.0.3 to 8.10.0

1.0.0

Major Changes

  • b58c70c223: This package has been promoted to v1.0! To understand how this change affects the package, please check out our versioning policy.

Minor Changes

  • 02ad19d189: BREAKING: Removed the deprecated metadata.generation field entirely. It is no longer present in TS types, nor in the REST API output. Entities that have not yet been re-stitched may still have the field present for some time, but it will get phased out gradually by your catalog instance.

  • a04dbc22d7: BREAKING: Removed EntityName, use CompoundEntityRef type instead.

    BREAKING: Removed getEntityName, use getCompoundEntityRef instead.

  • 132189e466: BREAKING: The User kind has an updated TypeScript type where spec.memberOf is optional.

    NOTE HOWEVER, that this only applies to the TypeScript types UserEntity and UserEntityV1alpha1. The catalog validation still requires the field to be set, even if it's in the form of an empty array. If you try to ingest data that stops producing this field, those entities will be rejected by the catalog. The reason for these choices is that consumers will get a long grace period where old code still can rely on the underlying data being present, giving users ample time to update before actual breakages could happen.

  • d3e9ec43b7: BREAKING: Removed the target property from EntityRelation. This field has been replaced by targetRef. This means that target: { name: 'team-a', kind: 'group', namespace: 'default' } is now replaced with targetRef: 'group:default/team-a' in entity relations.

    The entities API endpoint still return the old target field for to ease transitions, however the future removal of this field will be considered non breaking.

Patch Changes

0.13.0

Minor Changes

  • 51a9f8f122: BREAKING:

    • Removed the previously deprecated type EntityRef. Please use string for stringified entity refs, CompoundEntityRef for compound kind-namespace-name triplet objects, or custom objects like { kind?: string; namespace?: string; name: string } and similar if you have need for partial types.
    • Removed the previously deprecated type LocationSpec type, which has been moved to @backstage/plugin-catalog-backend.
    • Removed the previously deprecated function parseEntityName. Please use parseEntityRef instead.

  • d1d488e371: BREAKING: The default validator for metadata.tags now permits the colon (:) character as well.

Patch Changes

  • 2952566587: Updated parseEntityRef to allow : and / in the entity name. For example, parsing 'component:default/foo:bar' will result in the name 'foo:bar'.

    Note that only parsing 'foo:bar' itself will result in the name 'bar' and the entity kind 'foo', meaning this is a particularly nasty trap for user defined entity references. For this reason it is strongly discouraged to use names that contain these characters, and the catalog model does not allow it by default. However, this change now makes is possible to use these names if the default catalog validation is replaced, and in particular a high level of automation of the catalog population can limit issues that it might otherwise cause.

  • b1aacbf96a: Applied the fix for the /alpha entry point resolution that was part of the v0.70.1 release of Backstage.

  • d1d488e371: DEPRECATION:

    • Deprecated CommonValidatorFunctions.isValidString, please use isNonEmptyString instead which is equivalent but better named.
    • Deprecated CommonValidatorFunctions.isValidTag, with no replacement. Its purpose was too specific and not reusable, so it will be removed.

0.13.0-next.0

Minor Changes

  • 51a9f8f122: BREAKING:

    • Removed the previously deprecated type EntityRef. Please use string for stringified entity refs, CompoundEntityRef for compound kind-namespace-name triplet objects, or custom objects like { kind?: string; namespace?: string; name: string } and similar if you have need for partial types.
    • Removed the previously deprecated type LocationSpec type, which has been moved to @backstage/plugin-catalog-backend.
    • Removed the previously deprecated function parseEntityName. Please use parseEntityRef instead.

  • d1d488e371: BREAKING: The default validator for metadata.tags now permits the colon (:) character as well.

Patch Changes

  • 2952566587: Updated parseEntityRef to allow : and / in the entity name. For example, parsing 'component:default/foo:bar' will result in the name 'foo:bar'.

    Note that only parsing 'foo:bar' itself will result in the name 'bar' and the entity kind 'foo', meaning this is a particularly nasty trap for user defined entity references. For this reason it is strongly discouraged to use names that contain these characters, and the catalog model does not allow it by default. However, this change now makes is possible to use these names if the default catalog validation is replaced, and in particular a high level of automation of the catalog population can limit issues that it might otherwise cause.

  • b1aacbf96a: Applied the fix for the /alpha entry point resolution that was part of the v0.70.1 release of Backstage.

  • d1d488e371: DEPRECATION:

    • Deprecated CommonValidatorFunctions.isValidString, please use isNonEmptyString instead which is equivalent but better named.
    • Deprecated CommonValidatorFunctions.isValidTag, with no replacement. Its purpose was too specific and not reusable, so it will be removed.

0.12.1

Patch Changes

  • Fixed runtime resolution of the /alpha entry point.

0.12.0

Minor Changes

  • ac7b1161a6: BREAKING: The following changes are all breaking changes.

    Removed EDIT_URL_ANNOTATION and VIEW_URL_ANNOTATION, LOCATION_ANNOTATION, ORIGIN_LOCATION_ANNOTATION, LOCATION_ANNOTATION, SOURCE_LOCATION_ANNOTATION. All of these constants have been prefixed with ANNOTATION to be easier to find meaning SOURCE_LOCATION_ANNOTATION is available as ANNOTATION_SOURCE_LOCATION.

    Removed parseLocationReference, replaced by parseLocationRef.

    Removed stringifyLocationReference, replaced by stringifyLocationRef.

    Removed Location type which has been moved to catalog-client.

    Removed ENTITY_DEFAULT_NAMESPACE, replaced by DEFAULT_NAMESPACE.

    Removed compareEntityToRef compare using stringifyEntityRef instead.

    Removed JSONSchema type which should be imported from json-schema package instead.

    Removed utility methods: entityHasChanges, generateEntityEtag, generateEntityUid, generateUpdatedEntity.

    Removed ENTITY_META_GENERATED_FIELDS and EntityRefContext.

Patch Changes

  • debfcd9515: Move @types/json-schema to be a dev dependency

  • 36aa63022b: DEPRECATION: Deprecated the EntityName type, and added the better-named CompoundEntityRef to replace it.

    DEPRECATION: Deprecated the getEntityName function, and added the better-named getCompoundEntityRef to replace it.

    Please switch over to using the new symbols, as the old ones may be removed in a future release.

0.11.0

Minor Changes

  • 919cf2f836: BREAKING: Added EntityRelation.targetRef (a string form entity ref), and deprecated EntityRelation.target (a kind + namespace + name object). This aligns the type with our goal of using string form entity refs more coherently. There will be a period of time when both fields need to be present, which may in particular affect your tests which now have to list both the string form and the object form side by side.

     const mockEntity: Entity = {
   kind: 'Component',
   relations: [
     {
       type: RELATION_MEMBER_OF,
+      targetRef: 'component:default/foo',
       target: { kind: 'component', namespace: 'default', name: 'foo' }
     }
   ]

    The target field will be entirely removed from this type in a future release.

  • 7010349c9a: BREAKING: Removed EntityRelationSpec as it is only used during the catalog during the catalog processing.

  • 68f0871b76: BREAKING: Simplified the parseEntityRef function to always either return a complete EntityName, complete with both kind, namespace and name, or throw an error if it for some reason did not have enough information to form that result. This makes its usage and its type declaration vastly simpler.

Patch Changes

  • ed09ad8093: Deprecated the LocationSpec export, which should now be imported from @backstage/plugin-catalog-backend instead.
  • b5c02d10a6: Remove all usage of the deprecated ENTITY_DEFAULT_NAMESPACE
  • 67a7c02d26: DEPRECATED: The EntityRef type and parseEntityName function are now deprecated, and will soon be removed. This is part of a larger movement toward fixing the poorly named EntityName type which should instead have been named EntityRef. Please remove any usage of these as soon as possible.
  • da44c47f43: Deprecated the entity.metadata.generation as the field has never been fully functioning.

0.10.1

Patch Changes

0.10.0

Minor Changes

  • e483dd6c72: BREAKING: Remove deprecated validation methods analyzeLocationSchema, locationSchema and locationSpecSchema. This functionality was primarily used internally by the catalog-backend.
  • edbc03814a: BREAKING: Remove deprecated serializeEntityRef which is replaced by stringifyEntityRef.
  • e72d371296: BREAKING: Removed TemplateEntityV1beta2 from the model and moved it to @backstage/plugin-scaffolder-common where TemplateEntityV1beta3 already lived. It has also been marked as deprecated in the process - please consider migrating to v1beta3 templates.

Patch Changes

  • c77c5c7eb6: Added backstage.role to package.json
  • 216725b434: Deprecated parseLocationReference and stringifyLocationReference, introducing parseLocationRef and stringifyLocationRef in their place.
  • 244d24ebc4: Deprecates the Location type export from this package. Imports of the Location type should now be done from the @backstage/catalog-client package instead.
  • 7aeb491394: Deprecated ENTITY_DEFAULT_NAMESPACE constant in favour of DEFAULT_NAMESPACE.
  • 0d03e42a89: Deprecated compareEntityToRef due to low usage and provided value.
  • e8c6f9d282: Deprecated the EntityRefContext type which had limited use.
  • 7f21538c9e: Deprecated JSONSchema export type.
  • 20f3244102: Deprecates the following exports which all have very limited and internal use. ENTITY_META_GENERATED_FIELDS, entityHasChanges, generateEntityEtag, generateEntityUid, generateUpdatedEntity, ENTITY_META_GENERATED_FIELDS.
  • 27eccab216: Deprecates EDIT_URL_ANNOTATION, LOCATION_ANNOTATION, ORIGIN_LOCATION_ANNOTATION, SOURCE_LOCATION_ANNOTATION, VIEW_URL_ANNOTATION and replaces these constants all prefixed with ANNOTATION_ ANNOTATION_EDIT_URL, ANNOTATION_LOCATION, ANNOTATION_ORIGIN_LOCATION, ANNOTATION_SOURCE_LOCATION, ANNOTATION_VIEW_URL
  • Updated dependencies

0.9.10

Patch Changes

  • 8b5a7763d5: Added alpha release stage type declarations, accessible via @backstage/catalog-model/alpha.

    BREAKING: The experimental entity status field was removed from the base Entity type and is now only available on the AlphaEntity type from the alpha release stage, along with all accompanying types that were previously marked as UNSTABLE_.

    For example, the following import:

    import { UNSTABLE_EntityStatusItem } from '@backstage/catalog-model';

    Becomes this:

    import { EntityStatusItem } from '@backstage/catalog-model/alpha';

    Note that exports that are only available from the alpha release stage are considered unstable and do not adhere to the semantic versioning of the package.

  • Updated dependencies

0.9.10-next.0

Patch Changes

  • 8b5a7763d5: Added alpha release stage type declarations, accessible via @backstage/catalog-model/alpha.

    BREAKING: The experimental entity status field was removed from the base Entity type and is now only available on the AlphaEntity type from the alpha release stage, along with all accompanying types that were previously marked as UNSTABLE_.

    For example, the following import:

    import { UNSTABLE_EntityStatusItem } from '@backstage/catalog-model';

    Becomes this:

    import { EntityStatusItem } from '@backstage/catalog-model/alpha';

    Note that exports that are only available from the alpha release stage are considered unstable and do not adhere to the semantic versioning of the package.

  • Updated dependencies

0.9.9

Patch Changes

0.9.8

Patch Changes

  • ad7338bb48: Added an optional presence field to Location spec, which describes whether the target of a location is required to exist or not. It defaults to 'required', which is the current behaviour of the catalog.

0.9.7

Patch Changes

  • 8809b6c0dd: Update the json-schema dependency version.

0.9.6

Patch Changes

0.9.5

Patch Changes

0.9.4

Patch Changes

  • 957e4b3351: Updated dependencies
  • ca0559444c: Avoid usage of .to*Case(), preferring .toLocale*Case('en-US') instead.

0.9.3

Patch Changes

  • d42566c5c9: Loosen constraints on what's a valid catalog entity tag name (include + and #)
  • febddedcb2: Bump lodash to remediate SNYK-JS-LODASH-590103 security vulnerability
  • Updated dependencies

0.9.2

Patch Changes

0.9.1

Patch Changes

  • 13dc3735c: Add an optional metadata.title field to all entity kinds.

    This used to be available on only the Template kind, and we have decided that the metadata block should be the same for all kinds. A title can be useful especially in large and complex catalogs where users have a tough time navigating or discerning among the entities.

    It also carries some risk. You do not want to end up giving a title that collides with an actual name, which at best leads to confusion and at worst could be a liability. We do not perform any collision detection in the catalog. If you want to disallow this facility you may want to add a small processor that makes sure it's not set.

    At the time of writing this message, only the scaffolder actually makes use of this field for display purposes.

0.9.0

Minor Changes

  • 77db0c454: Changed the regex to validate names following the Kubernetes validation rule, this allow to be more permissive validating the name of the object in Backstage.

  • 60e830222: Support for Template kinds with version backstage.io/v1alpha1 has now been removed. This means that the old method of running templates with Preparers, Templaters and Publishers has also been removed. If you had any logic in these abstractions, they should now be moved to actions instead, and you can find out more about those in the documentation

    If you need any help migrating existing templates, there's a migration guide. Reach out to us on Discord in the #support channel if you're having problems.

    The scaffolder-backend now no longer requires these Preparers, Templaters, and Publishers to be passed in, now all it needs is the containerRunner.

    Please update your packages/backend/src/plugins/scaffolder.ts like the following

    - import {
-  DockerContainerRunner,
-  SingleHostDiscovery,
- } from '@backstage/backend-common';
+ import { DockerContainerRunner } from '@backstage/backend-common';
  import { CatalogClient } from '@backstage/catalog-client';
- import {
-   CookieCutter,
-   CreateReactAppTemplater,
-   createRouter,
-   Preparers,
-   Publishers,
-   Templaters,
- } from '@backstage/plugin-scaffolder-backend';
+ import { createRouter } from '@backstage/plugin-scaffolder-backend';
  import Docker from 'dockerode';
  import { Router } from 'express';
  import type { PluginEnvironment } from '../types';

  export default async function createPlugin({
    config,
    database,
    reader,
+   discovery,
  }: PluginEnvironment): Promise<Router> {
    const dockerClient = new Docker();
    const containerRunner = new DockerContainerRunner({ dockerClient });

-   const cookiecutterTemplater = new CookieCutter({ containerRunner });
-   const craTemplater = new CreateReactAppTemplater({ containerRunner });
-   const templaters = new Templaters();

-   templaters.register('cookiecutter', cookiecutterTemplater);
-   templaters.register('cra', craTemplater);
-
-   const preparers = await Preparers.fromConfig(config, { logger });
-   const publishers = await Publishers.fromConfig(config, { logger });

-   const discovery = SingleHostDiscovery.fromConfig(config);
    const catalogClient = new CatalogClient({ discoveryApi: discovery });

    return await createRouter({
-     preparers,
-     templaters,
-     publishers,
+     containerRunner,
      logger,
      config,
      database,

0.8.4

Patch Changes

  • 48c9fcd33: Migrated to use the new @backstage/core-* packages rather than @backstage/core.

0.8.3

Patch Changes

  • 1d2ed7844: Removed unused typescript-json-schema dependency.

0.8.2

Patch Changes

  • 27a9b503a: Introduce conditional steps in scaffolder templates.

    A step can now include an if property that only executes a step if the condition is truthy. The condition can include handlebar templates.

    - id: register
    if: '{{ not parameters.dryRun }}'
    name: Register
    action: catalog:register
    input:
    repoContentsUrl: '{{ steps.publish.output.repoContentsUrl }}'
    catalogInfoPath: '/catalog-info.yaml'

    Also introduces a not helper in handlebar templates that allows to negate boolean expressions.

0.8.1

Patch Changes

  • ebe802bc4: Remove the explicit connection from EntityEnvelope and Entity.

0.8.0

Minor Changes

  • 704875e26: Breaking changes:

    • The long-deprecated schemaValidator export is finally removed.

    Additions:

    • The EntityEnvelope type, which is a supertype of Entity.
    • The entityEnvelopeSchemaValidator function, which returns a validator for an EntityEnvelope or its subtypes, based on a JSON schema.
    • The entitySchemaValidator function, which returns a validator for an Entity or its subtypes, based on a JSON schema.
    • The entityKindSchemaValidator function, which returns a specialized validator for custom Entity kinds, based on a JSON schema.

Patch Changes

  • add62a455: Foundation for standard entity status values

0.7.10

Patch Changes

  • f7f7783a3: Add Owner field in template card and new data distribution Add spec.owner as optional field into TemplateV1Alpha and TemplateV1Beta Schema Add relations ownedBy and ownerOf into Template entity Template documentation updated
  • 68fdbf014: Add the status field to the Entity envelope

0.7.9

Patch Changes

  • 10c008a3a: Renamed parameters to input in template schema
  • 16be1d093: Improve error messages when schema validation fails

0.7.8

Patch Changes

  • d8b81fd28: Bump json-schema dependency from 0.2.5 to 0.3.0.
  • Updated dependencies [d8b81fd28]

0.7.7

Patch Changes

  • bb5055aee: Add getEntitySourceLocation helper

  • 5d0740563: Implemented missing support for the dependsOn/dependencyOf relationships between Component and Resource catalog model objects.

    Added support for generating the relevant relationships to the BuiltinKindsEntityProcessor, and added simple support for fetching relationships between Components and Resources for rendering in the system diagram. All catalog-model changes backwards compatible.

0.7.6

Patch Changes

  • 97b60de98: Added stringifyEntityRef, which always creates a string representation of an entity reference. Also deprecated serializeEntityRef, as stringifyEntityRef should be used instead.
  • 98dd5da71: Add support for multiple links to post-scaffold task summary page

0.7.5

Patch Changes

  • 8488a1a96: Added support for the "members" field of the Group entity, allowing specification of direct members from the Group side of the relationship. Added support to the BuiltinKindsEntityProcessor to generate the appropriate relationships.

0.7.4

Patch Changes

  • 0b42fff22: Add parseLocationReference, stringifyLocationReference

0.7.3

Patch Changes

  • 12d8f27a6: Add version backstage.io/v1beta2 schema for Template entities.

0.7.2

Patch Changes

  • bad21a085: Implement annotations for customising Entity URLs in the Catalog pages.
  • Updated dependencies [a1f5e6545]

0.7.1

Patch Changes

  • 6e612ce25: Adds a new optional links metadata field to the Entity class within the catalog-model package (as discussed in [RFC] Entity Links). This PR adds support for the entity links only. Follow up PR's will introduce the UI component to display them.
  • 025e122c3: Replace yup with ajv, for validation of catalog entities.
  • 7881f2117: Introduce json schema variants of the yup validation schemas
  • 11cb5ef94: Implement matchEntityWithRef for client side filtering of entities by ref matching

0.7.0

Minor Changes

  • a93f42213: The catalog no longer attempts to merge old and new annotations, when updating an entity from a remote location. This was a behavior that was copied from kubernetes, and catered to use cases where you wanted to use HTTP POST to update an entity in-place, outside of what the refresh loop does. This has proved to be a mistake, because as a side effect, the refresh loop effectively is unable to ever delete annotations when they are removed from source YAML. This is obviously a breaking change, but we believe that this is not a behavior that is relied upon in the wild, and it has never been an actually supported use flow of the catalog. We therefore choose to break the behavior outright, and instead just store updated annotations verbatim - just like we already do for example for labels

Patch Changes

  • def2307f3: Adds a backstage.io/managed-by-origin-location annotation to all entities. It links to the location that was registered to the catalog and which emitted this entity. It has a different semantic than the existing backstage.io/managed-by-location annotation, which tells the direct parent location that created this entity.

    Consider this example: The Backstage operator adds a location of type github-org in the app-config.yaml. This setting will be added to a bootstrap:boostrap location. The processor discovers the entities in the following branch Location bootstrap:bootstrap -> Location github-org:… -> User xyz. The user xyz will be:

    apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: xyz
  annotations:
    # This entity was added by the 'github-org:…' location
    backstage.io/managed-by-location: github-org:…
    # The entity was added because the 'bootstrap:boostrap' was added to the catalog
    backstage.io/managed-by-origin-location: bootstrap:bootstrap
    # ...
spec:
  # ...

0.6.1

Patch Changes

  • f3b064e1c: Export the schemaValidator helper function.
  • abbee6fff: Implement System, Domain and Resource entity kinds.
  • 147fadcb9: Add subcomponentOf to Component kind to represent subsystems of larger components.

0.6.0

Minor Changes

  • ac3560b42: Remove implementsApis from Component entities. Deprecation happened in #3449. Use providesApis instead.

Patch Changes

  • c911061b7: Introduce a profile section for group entities that can optional include a displayName, email and picture.
  • 0e6298f7e: Ignore relations when comparing entities. This stops the refresh loop from rewriting entities over and over.

0.5.0

Minor Changes

Patch Changes

0.4.0

Minor Changes

  • bcc211a08: k8s-plugin: refactor approach to use annotation based label-selector

Patch Changes

  • 08835a61d: Add support for relative targets and implicit types in Location entities.

  • a9fd599f7: Add Analyze location endpoint to catalog backend. Add catalog-import plugin and replace import-component with it. To start using Analyze location endpoint, you have add it to the createRouter function options in the \backstage\packages\backend\src\plugins\catalog.ts file:

    export default async function createPlugin(env: PluginEnvironment) {
  const builder = new CatalogBuilder(env);
  const {
    entitiesCatalog,
    locationsCatalog,
    higherOrderOperation,
    locationAnalyzer, //<--
  } = await builder.build();

  return await createRouter({
    entitiesCatalog,
    locationsCatalog,
    higherOrderOperation,
    locationAnalyzer, //<--
    logger: env.logger,
  });
}

0.3.1

Patch Changes

  • ab94c9542: Add providesApis and consumesApis to the component entity spec.
  • 2daf18e80: Start emitting all known relation types from the core entity kinds, based on their spec data.

  • 069cda35f: Marked the field spec.implementsApis on Component entities for deprecation on Dec 14th, 2020.

    Code that consumes these fields should remove those usages as soon as possible and migrate to using relations instead. Producers should fill the field spec.providesApis instead, which has the same semantic.

    After Dec 14th, the fields will be removed from types and classes of the Backstage repository. At the first release after that, they will not be present in released packages either.

    If your catalog-info.yaml files still contain this field after the deletion, they will still be valid and your ingestion will not break, but they won't be visible in the types for consuming code, and the expected relations will not be generated based on them either.

0.3.0

Minor Changes

  • 1166fcc36: add kubernetes selector to component model

Patch Changes

  • 1185919f3: Marked the Group entity fields ancestors and descendants for deprecation on Dec 6th, 2020. See https://github.com/backstage/backstage/issues/3049 for details.

    Code that consumes these fields should remove those usages as soon as possible. There is no current or planned replacement for these fields.

    The BuiltinKindsEntityProcessor has been updated to inject these fields as empty arrays if they are missing. Therefore, if you are on a catalog instance that uses the updated version of this code, you can start removing the fields from your source catalog-info.yaml data as well, without breaking validation.

    After Dec 6th, the fields will be removed from types and classes of the Backstage repository. At the first release after that, they will not be present in released packages either.

    If your catalog-info.yaml files still contain these fields after the deletion, they will still be valid and your ingestion will not break, but they won't be visible in the types for consuming code.

0.2.0

Minor Changes

  • 3a4236570: Add handling and docs for entity references
  • e0be86b6f: Entirely case insensitive read path of entities

  • f70a52868: Add the User & Group entities

    A user describes a person, such as an employee, a contractor, or similar. Users belong to Group entities in the catalog.

    A group describes an organizational entity, such as for example a team, a business unit, or a loose collection of people in an interest group. Members of these groups are modeled in the catalog as kind User.

  • 12b5fe940: Add ApiDefinitionAtLocationProcessor that allows to load a API definition from another location

  • a768a07fb: Add the ability to import users from GitHub Organization into the catalog.

  • 5adfc005e: Changes the various kind policies into a new type KindValidator.

    Adds CatalogProcessor#validateEntityKind that makes use of the above validators. This moves entity schema validity checking away from entity policies and into processors, centralizing the extension points into the processor chain.

  • b3d57961c: Enable adding locations for config files that does not yet exist by adding a flag to api request

Patch Changes

  • fa56f4615: Fix documentation and validation message for tags