feat(dev-ui): add ui component metadata

Author: MichaelDoyle

js/core/src/error.ts

@@ -15,8 +15,13 @@
  */
 
 import type { Registry } from './registry.js';
-import { httpStatusCode, type StatusName } from './statusTypes.js';
+import {
+  StatusNameSchema,
+  httpStatusCode,
+  type StatusName,
+} from './statusTypes.js';
 
+export { StatusNameSchema };
 export type { StatusName };
 
 export interface HttpErrorWireFormat {

js/core/src/index.ts

@@ -65,6 +65,7 @@ export {
 } from './dynamic-action-provider.js';
 export {
   GenkitError,
+  StatusNameSchema,
   UnstableApiError,
   UserFacingError,
   assertUnstable,
@@ -91,6 +92,11 @@ export {
   toJsonSchema,
   type JSONSchema,
 } from './schema.js';
+export {
+  GENKIT_UI_WIDGETS,
+  GENKIT_UI_METADATA,
+  type GenkitUiWidget,
+} from './metadata.js';
 export * from './telemetryTypes.js';
 export * from './utils.js';
 

js/core/src/metadata.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Metadata keys used for UI-specific schema annotations.
+ */
+export const GENKIT_UI_METADATA = {
+  /**
+   * Provides data to populate both standard and customized UI widgets.
+   *
+   * e.g.
+   *
+   * {
+   *   [GENKIT_UI_METADATA.DATA_SOURCE]: {
+   *     action: '/custom/foo',
+   *     allowCustomValues: true
+   *   }
+   * }
+   */
+  DATA_SOURCE: 'x-genkit-ui-data-source',
+
+  /**
+   * Provides a display name or label for the UI. By default, the Dev UI will
+   * transform schema fields to "Sentence case". There are times where this is
+   * not desirable and needs to be overwritten, such as abbreviations or
+   * acronyms (e.g. "Top P", "Top K") and proper nouns (e.g. "Google Search
+   * retrieval").
+   *
+   * e.g. { [GENKIT_UI_METADATA.DISPLAY_NAME]: 'Top P' }
+   */
+  DISPLAY_NAME: 'x-genkit-ui-display-name',
+
+  /**
+   * Specifies the UI component (widget) to use for a schema field. Commonly
+   * used for model and middleware configuration. Useful to resolve ambiguity
+   * when multiple inputs could apply, or to provide a tailored user experience
+   * for complex inputs.
+   *
+   * e.g. { [GENKIT_UI_METADATA.WIDGET]: GENKIT_UI_WIDGETS.MODEL_LIST }
+   */
+  WIDGET: 'x-genkit-ui-widget',
+} as const;
+
+/**
+ * Standard UI widget names used with GENKIT_UI_METADATA.WIDGET.
+ */
+export const GENKIT_UI_WIDGETS = {
+  /** A widget for configuring a list of models. */
+  MODEL_LIST: 'model-list-config',
+  /** A widget for configuring LLM model safety settings. */
+  SAFETY_SETTINGS: 'safety-settings',
+} as const;
+
+/**
+ * Union type of standard Genkit UI widget names.
+ */
+export type GenkitUiWidget =
+  (typeof GENKIT_UI_WIDGETS)[keyof typeof GENKIT_UI_WIDGETS];

js/core/tests/schema_test.ts

@@ -18,6 +18,7 @@ import Ajv from 'ajv';
 import * as assert from 'assert';
 import { afterEach, describe, it, mock } from 'node:test';
 
+import { GENKIT_UI_METADATA } from '../src/metadata.js';
 import { setGenkitRuntimeConfig } from '../src/config.js';
 import {
   ValidationError,
@@ -169,48 +170,48 @@ describe('toJsonSchema', () => {
 describe('annotateSchema()', () => {
   it('should merge annotations into the JSON schema', () => {
     const schema = annotateSchema(z.string(), {
-      'x-genkit-data-source': 'my-action',
+      [GENKIT_UI_METADATA.DATA_SOURCE]: 'my-action',
     });
 
     const json = toJsonSchema({ schema });
-    assert.strictEqual(json['x-genkit-data-source'], 'my-action');
+    assert.strictEqual(json[GENKIT_UI_METADATA.DATA_SOURCE], 'my-action');
   });
 
   it('should merge annotations for nested fields', () => {
     const schema = z.object({
       field: annotateSchema(z.string(), {
-        'x-genkit-data-source': 'nested-action',
+        [GENKIT_UI_METADATA.DATA_SOURCE]: 'nested-action',
       }),
     });
 
     const json = toJsonSchema({ schema });
     assert.strictEqual(
-      json.properties.field['x-genkit-data-source'],
+      json.properties.field[GENKIT_UI_METADATA.DATA_SOURCE],
       'nested-action'
     );
   });
 
   it('should merge annotations for array items', () => {
     const schema = z.array(
       annotateSchema(z.string(), {
-        'x-genkit-data-source': 'array-action',
+        [GENKIT_UI_METADATA.DATA_SOURCE]: 'array-action',
       })
     );
 
     const json = toJsonSchema({ schema });
-    assert.strictEqual(json.items['x-genkit-data-source'], 'array-action');
+    assert.strictEqual(json.items[GENKIT_UI_METADATA.DATA_SOURCE], 'array-action');
   });
 
   it('should merge annotations for optional fields', () => {
     const schema = z.object({
       field: annotateSchema(z.string(), {
-        'x-genkit-data-source': 'optional-action',
+        [GENKIT_UI_METADATA.DATA_SOURCE]: 'optional-action',
       }).optional(),
     });
 
     const json = toJsonSchema({ schema });
     assert.strictEqual(
-      json.properties.field['x-genkit-data-source'],
+      json.properties.field[GENKIT_UI_METADATA.DATA_SOURCE],
       'optional-action'
     );
   });

js/genkit/src/common.ts

@@ -136,8 +136,11 @@ export {
   OperationSchema,
   ReflectionServer,
   StatusCodes,
+  StatusNameSchema,
   StatusSchema,
   UserFacingError,
+  GENKIT_UI_WIDGETS,
+  GENKIT_UI_METADATA,
   annotateSchema,
   defineJsonSchema,
   defineSchema,
@@ -160,6 +163,7 @@ export {
   type FlowFn,
   type FlowSideChannel,
   type GenkitRuntimeConfig,
+  type GenkitUiWidget,
   type JSONSchema,
   type JSONSchema7,
   type Middleware,

js/plugins/google-genai/src/googleai/gemini.ts

@@ -14,17 +14,25 @@
  * limitations under the License.
  */
 
-import { ActionMetadata, GenkitError, modelActionMetadata, z } from 'genkit';
+import {
+  ActionMetadata,
+  annotateSchema,
+  GENKIT_UI_WIDGETS,
+  GENKIT_UI_METADATA,
+  GenkitError,
+  modelActionMetadata,
+  z,
+} from 'genkit';
 import {
   CandidateData,
   GenerationCommonConfigDescriptions,
   GenerationCommonConfigSchema,
+  getBasicUsageStats,
   ModelAction,
   ModelInfo,
   ModelMiddleware,
-  ModelReference,
-  getBasicUsageStats,
   modelRef,
+  ModelReference,
 } from 'genkit/model';
 import { downloadRequestMedia } from 'genkit/model/middleware';
 import { model as pluginModel } from 'genkit/plugin';
@@ -154,13 +162,16 @@ export const GeminiConfigSchema = GenerationCommonConfigSchema.extend({
       'Overrides the plugin-configured or default apiVersion, if specified.'
     )
     .optional(),
-  safetySettings: z
-    .array(SafetySettingsSchema)
-    .describe(
-      'Adjust how likely you are to see responses that could be harmful. ' +
-        'Content is blocked based on the probability that it is harmful.'
-    )
-    .optional(),
+  safetySettings: annotateSchema(
+    z
+      .array(SafetySettingsSchema)
+      .describe(
+        'Adjust how likely you are to see responses that could be harmful. ' +
+          'Content is blocked based on the probability that it is harmful.'
+      )
+      .optional(),
+    { [GENKIT_UI_METADATA.WIDGET]: GENKIT_UI_WIDGETS.SAFETY_SETTINGS }
+  ),
   codeExecution: z
     .union([z.boolean(), z.object({}).strict()])
     .describe('Enables the model to generate and run code.')

js/plugins/google-genai/src/vertexai/gemini.ts

@@ -14,17 +14,25 @@
  * limitations under the License.
  */
 
-import { ActionMetadata, GenkitError, modelActionMetadata, z } from 'genkit';
+import {
+  ActionMetadata,
+  annotateSchema,
+  GENKIT_UI_WIDGETS,
+  GENKIT_UI_METADATA,
+  GenkitError,
+  modelActionMetadata,
+  z,
+} from 'genkit';
 import {
   CandidateData,
   GenerationCommonConfigDescriptions,
   GenerationCommonConfigSchema,
+  getBasicUsageStats,
   ModelAction,
   ModelInfo,
   ModelMiddleware,
-  ModelReference,
-  getBasicUsageStats,
   modelRef,
+  ModelReference,
 } from 'genkit/model';
 import { downloadRequestMedia } from 'genkit/model/middleware';
 import { model as pluginModel } from 'genkit/plugin';
@@ -185,13 +193,16 @@ export const GeminiConfigSchema = GenerationCommonConfigSchema.extend({
    * }
    * ```
    */
-  safetySettings: z
-    .array(SafetySettingsSchema)
-    .describe(
-      'Adjust how likely you are to see responses that could be harmful. ' +
-        'Content is blocked based on the probability that it is harmful.'
-    )
-    .optional(),
+  safetySettings: annotateSchema(
+    z
+      .array(SafetySettingsSchema)
+      .describe(
+        'Adjust how likely you are to see responses that could be harmful. ' +
+          'Content is blocked based on the probability that it is harmful.'
+      )
+      .optional(),
+    { [GENKIT_UI_METADATA.WIDGET]: GENKIT_UI_WIDGETS.SAFETY_SETTINGS }
+  ),
 
   /**
    * Vertex retrieval options.

js/plugins/middleware/src/fallback.ts

@@ -15,8 +15,12 @@
  */
 
 import {
+  GENKIT_UI_WIDGETS,
+  GENKIT_UI_METADATA,
   GenkitError,
   ModelReferenceSchema,
+  StatusNameSchema,
+  annotateSchema,
   generateMiddleware,
   z,
   type GenerateMiddleware,
@@ -40,15 +44,18 @@ export const FallbackOptionsSchema = z
     /**
      * An array of models to try in order.
      */
-    models: z
-      .array(ModelReferenceSchema)
-      .describe('An array of models to try in order.'),
+    models: annotateSchema(
+      z
+        .array(ModelReferenceSchema)
+        .describe('An array of models to try in order.'),
+      { [GENKIT_UI_METADATA.WIDGET]: GENKIT_UI_WIDGETS.MODEL_LIST }
+    ),
     /**
      * An array of `StatusName` values that should trigger a fallback.
      * @default ['UNAVAILABLE', 'DEADLINE_EXCEEDED', 'RESOURCE_EXHAUSTED', 'ABORTED', 'INTERNAL', 'NOT_FOUND', 'UNIMPLEMENTED']
      */
     statuses: z
-      .array(z.string())
+      .array(StatusNameSchema)
       .optional()
       .describe(
         'An array of StatusName values that should trigger a fallback.'

js/plugins/middleware/src/retry.ts

@@ -17,6 +17,7 @@
 import {
   GenerateMiddleware,
   GenkitError,
+  StatusNameSchema,
   generateMiddleware,
   z,
   type StatusName,
@@ -38,7 +39,7 @@ export const RetryOptionsSchema = z
      * @default ['UNAVAILABLE', 'DEADLINE_EXCEEDED', 'RESOURCE_EXHAUSTED', 'ABORTED', 'INTERNAL']
      */
     statuses: z
-      .array(z.string())
+      .array(StatusNameSchema)
       .optional()
       .describe('An array of StatusName values that should trigger a retry.'),
     /**