add documentation for async field extension validators

Signed-off-by: Stephen Glass <stephen@stephen.glass>
2025-01-09 00:55:33 -05:00
parent 29596ac09c
commit a46aebbd07
1 changed files with 26 additions and 0 deletions
@@ -150,6 +150,32 @@ const routes = (
 );
 ```

+### Async Validation Function
+
+A validation function can be asyncronous and use [Utility APIs](https://backstage.io/docs/api/utility-apis/) via the `ApiHolder` in the [field validation context](https://backstage.io/docs/reference/plugin-scaffolder-react.customfieldvalidator). The example below uses the `catalogApiRef` to check if the submitted value (in this scenario an entity ref) exists in the catalog.
+
+```tsx
+import { FieldValidation } from '@rjsf/utils';
+import { ApiHolder } from '@backstage/core-plugin-api';
+import { catalogApiRef } from '@backstage/plugin-catalog-react';
+
+/*
+  This validation function checks if the submitted entity ref value is present in the catalog.
+*/
+
+export const customFieldExtensionValidator = async (
+  value: string,
+  validation: FieldValidation,
+  context: { apiHolder: ApiHolder },
+) => {
+  const catalogApi = context.apiHolder.get(catalogApiRef);
+
+  if ((await catalogApi?.getEntityByRef(value)) === undefined) {
+    validation.addError('Entity not found');
+  }
+};
+```
+
 ## Using the Custom Field Extension

 Once it's been passed to the `ScaffolderPage` you should now be able to use the