Merge pull request #9671 from backstage/freben/targetRef

add `EntityRelation.targetRef`

.changeset/brown-chairs-punch.md

@@ -0,0 +1,13 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+The catalog API now returns entity relations that have three fields: The old
+`type` and `target` fields, as well as a new `targetRef` field. The last one is
+the stringified form of the second one.
+
+**DEPRECATION**: The `target` field is hereby deprecated, both as seen from the
+catalog API as well as from the `@backstage/catalog-model` package. Both
+`target` and `targetRef` will be produced for some time, but eventually,
+`target` will be removed entirely. Please update your readers to stop consuming
+the `relations.[].target` field from the catalog API as soon as possible.

.changeset/kind-cobras-admire.md

@@ -0,0 +1,24 @@
+---
+'@backstage/catalog-model': minor
+---
+
+**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.
+
+```diff
+ 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.

.changeset/yellow-goats-drop.md

@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-api-docs': patch
+'@backstage/plugin-auth-backend': patch
+'@backstage/plugin-catalog': patch
+'@backstage/plugin-catalog-graph': patch
+'@backstage/plugin-catalog-react': patch
+'@backstage/plugin-fossa': patch
+'@backstage/plugin-org': patch
+'@backstage/plugin-tech-insights-backend': patch
+'@backstage/plugin-techdocs': patch
+'@backstage/plugin-techdocs-backend': patch
+---
+
+Minor updates to match the new `targetRef` field of relations, and to stop consuming the `target` field