catalog-model: add presence field to locations

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/sweet-camels-learn.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': patch
+---
+
+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.

packages/catalog-model/api-report.md

@@ -325,6 +325,7 @@ interface LocationEntityV1alpha1 extends Entity {
     type?: string;
     target?: string;
     targets?: string[];
+    presence?: 'required' | 'optional';
   };
 }
 export { LocationEntityV1alpha1 as LocationEntity };

packages/catalog-model/src/kinds/LocationEntityV1alpha1.test.ts

@@ -102,4 +102,23 @@ describe('LocationV1alpha1Validator', () => {
     (entity as any).spec.targets = 7;
     await expect(validator.check(entity)).rejects.toThrow(/targets/);
   });
+
+  it('accepts good presence', async () => {
+    (entity as any).spec.presence = 'required';
+    await expect(validator.check(entity)).resolves.toBe(true);
+    (entity as any).spec.presence = 'optional';
+    await expect(validator.check(entity)).resolves.toBe(true);
+  });
+
+  it('rejects empty presence', async () => {
+    (entity as any).spec.presence = '';
+    await expect(validator.check(entity)).rejects.toThrow(/presence/);
+  });
+
+  it('rejects wrong presence', async () => {
+    (entity as any).spec.presence = 7;
+    await expect(validator.check(entity)).rejects.toThrow(/presence/);
+    (entity as any).spec.presence = 'nope';
+    await expect(validator.check(entity)).rejects.toThrow(/presence/);
+  });
 });

packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts

@@ -30,6 +30,7 @@ export interface LocationEntityV1alpha1 extends Entity {
     type?: string;
     target?: string;
     targets?: string[];
+    presence?: 'required' | 'optional';
   };
 }
 

packages/catalog-model/src/schema/kinds/Location.v1alpha1.schema.json

@@ -59,6 +59,13 @@
                 ],
                 "minLength": 1
               }
+            },
+            "presence": {
+              "type": "string",
+              "description": "Whether the presence of the location target is required and it should be considered an error if it can not be found",
+              "default": "required",
+              "examples": ["required"],
+              "enum": ["required", "optional"]
             }
           }
         }