Merge pull request #28418 from stephenglass/docs-field-validators

add documentation for async field extension validators

docs/features/software-templates/writing-custom-field-extensions.md

@@ -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