Merge pull request #28798 from backstage/blam/zod-types

Deprecate `createTemplateAction` with old `JSONSchema` and `zod` declarations

plugins/scaffolder-node/src/actions/createTemplateAction.test.ts

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2025 The Backstage Authors
+ *
+ * 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.
+ */
+import { createTemplateAction } from './createTemplateAction';
+import { z } from 'zod';
+
+describe('createTemplateAction', () => {
+  it('should allow creating with jsonschema and use the old deprecated types', () => {
+    const action = createTemplateAction<{ repoUrl: string }, { test: string }>({
+      id: 'test',
+      schema: {
+        input: {
+          type: 'object',
+          required: ['repoUrl'],
+          properties: {
+            repoUrl: { type: 'string' },
+          },
+        },
+        output: {
+          type: 'object',
+          required: ['test'],
+          properties: {
+            test: { type: 'string' },
+          },
+        },
+      },
+      handler: async ctx => {
+        // @ts-expect-error - repoUrl is string
+        const a: number = ctx.input.repoUrl;
+
+        const b: string = ctx.input.repoUrl;
+        expect(b).toBeDefined();
+
+        const stream = ctx.logStream;
+        expect(stream).toBeDefined();
+
+        ctx.output('test', 'value');
+
+        // @ts-expect-error - not valid output type
+        ctx.output('test', 4);
+
+        // @ts-expect-error - not valid output name
+        ctx.output('test2', 'value');
+      },
+    });
+
+    expect(action).toBeDefined();
+  });
+
+  it('should allow creating with zod and use the old deprecated types', () => {
+    const action = createTemplateAction({
+      id: 'test',
+      schema: {
+        input: z.object({
+          repoUrl: z.string(),
+        }),
+        output: z.object({
+          test: z.string(),
+        }),
+      },
+      handler: async ctx => {
+        // @ts-expect-error - repoUrl is string
+        const a: number = ctx.input.repoUrl;
+
+        const b: string = ctx.input.repoUrl;
+        expect(b).toBeDefined();
+
+        const stream = ctx.logStream;
+        expect(stream).toBeDefined();
+
+        ctx.output('test', 'value');
+
+        // @ts-expect-error - not valid output type
+        ctx.output('test', 4);
+
+        // @ts-expect-error - not valid output name
+        ctx.output('test2', 'value');
+      },
+    });
+
+    expect(action).toBeDefined();
+  });
+
+  it('should allow creating with new first class zod support', () => {
+    const action = createTemplateAction({
+      id: 'test',
+      schema: {
+        input: {
+          repoUrl: d => d.string(),
+        },
+        output: {
+          test: d => d.string(),
+        },
+      },
+      handler: async ctx => {
+        // @ts-expect-error - repoUrl is string
+        const a: number = ctx.input.repoUrl;
+
+        const b: string = ctx.input.repoUrl;
+        expect(b).toBeDefined();
+
+        // @ts-expect-error - logStream is not available
+        const stream = ctx.logStream;
+
+        expect(stream).toBeDefined();
+
+        ctx.output('test', 'value');
+
+        // @ts-expect-error - not valid output type
+        ctx.output('test', 4);
+
+        // @ts-expect-error - not valid output name
+        ctx.output('test2', 'value');
+      },
+    });
+
+    expect(action).toBeDefined();
+  });
+});

plugins/scaffolder-node/src/actions/createTemplateAction.ts

@@ -16,9 +16,8 @@
 
 import { ActionContext, TemplateAction } from './types';
 import { z } from 'zod';
-import { Schema } from 'jsonschema';
-import zodToJsonSchema from 'zod-to-json-schema';
-import { JsonObject } from '@backstage/types';
+import { Expand, JsonObject } from '@backstage/types';
+import { parseSchemas } from './util';
 
 /** @public */
 export type TemplateExample = {
@@ -30,8 +29,15 @@ export type TemplateExample = {
 export type TemplateActionOptions<
   TActionInput extends JsonObject = {},
   TActionOutput extends JsonObject = {},
-  TInputSchema extends Schema | z.ZodType = {},
-  TOutputSchema extends Schema | z.ZodType = {},
+  TInputSchema extends
+    | JsonObject
+    | z.ZodType
+    | { [key in string]: (zImpl: typeof z) => z.ZodType } = JsonObject,
+  TOutputSchema extends
+    | JsonObject
+    | z.ZodType
+    | { [key in string]: (zImpl: typeof z) => z.ZodType } = JsonObject,
+  TSchemaType extends 'v1' | 'v2' = 'v1' | 'v2',
 > = {
   id: string;
   description?: string;
@@ -41,25 +47,112 @@ export type TemplateActionOptions<
     input?: TInputSchema;
     output?: TOutputSchema;
   };
-  handler: (ctx: ActionContext<TActionInput, TActionOutput>) => Promise<void>;
+  handler: (
+    ctx: ActionContext<TActionInput, TActionOutput, TSchemaType>,
+  ) => Promise<void>;
 };
 
+/**
+ * @ignore
+ */
+type FlattenOptionalProperties<T extends { [key in string]: unknown }> = Expand<
+  {
+    [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+  } & {
+    [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
+  }
+>;
+
+/**
+ * @public
+ * @deprecated migrate to using the new built in zod schema definitions for schemas
+ */
+export function createTemplateAction<
+  TInputParams extends JsonObject = JsonObject,
+  TOutputParams extends JsonObject = JsonObject,
+  TInputSchema extends JsonObject = JsonObject,
+  TOutputSchema extends JsonObject = JsonObject,
+  TActionInput extends JsonObject = TInputParams,
+  TActionOutput extends JsonObject = TOutputParams,
+>(
+  action: TemplateActionOptions<
+    TActionInput,
+    TActionOutput,
+    TInputSchema,
+    TOutputSchema,
+    'v1'
+  >,
+): TemplateAction<TActionInput, TActionOutput, 'v1'>;
+/**
+ * @public
+ * @deprecated migrate to using the new built in zod schema definitions for schemas
+ */
+export function createTemplateAction<
+  TInputParams extends JsonObject = JsonObject,
+  TOutputParams extends JsonObject = JsonObject,
+  TInputSchema extends z.ZodType = z.ZodType,
+  TOutputSchema extends z.ZodType = z.ZodType,
+  TActionInput extends JsonObject = z.infer<TInputSchema>,
+  TActionOutput extends JsonObject = z.infer<TOutputSchema>,
+>(
+  action: TemplateActionOptions<
+    TActionInput,
+    TActionOutput,
+    TInputSchema,
+    TOutputSchema,
+    'v1'
+  >,
+): TemplateAction<TActionInput, TActionOutput, 'v1'>;
 /**
  * This function is used to create new template actions to get type safety.
  * Will convert zod schemas to json schemas for use throughout the system.
  * @public
  */
-export const createTemplateAction = <
+export function createTemplateAction<
+  TInputSchema extends { [key in string]: (zImpl: typeof z) => z.ZodType },
+  TOutputSchema extends { [key in string]: (zImpl: typeof z) => z.ZodType },
+>(
+  action: TemplateActionOptions<
+    {
+      [key in keyof TInputSchema]: z.infer<ReturnType<TInputSchema[key]>>;
+    },
+    {
+      [key in keyof TOutputSchema]: z.infer<ReturnType<TOutputSchema[key]>>;
+    },
+    TInputSchema,
+    TOutputSchema,
+    'v2'
+  >,
+): TemplateAction<
+  FlattenOptionalProperties<{
+    [key in keyof TInputSchema]: z.output<ReturnType<TInputSchema[key]>>;
+  }>,
+  FlattenOptionalProperties<{
+    [key in keyof TOutputSchema]: z.output<ReturnType<TOutputSchema[key]>>;
+  }>,
+  'v2'
+>;
+export function createTemplateAction<
   TInputParams extends JsonObject = JsonObject,
   TOutputParams extends JsonObject = JsonObject,
-  TInputSchema extends Schema | z.ZodType = {},
-  TOutputSchema extends Schema | z.ZodType = {},
+  TInputSchema extends
+    | JsonObject
+    | z.ZodType
+    | { [key in string]: (zImpl: typeof z) => z.ZodType } = JsonObject,
+  TOutputSchema extends
+    | JsonObject
+    | z.ZodType
+    | { [key in string]: (zImpl: typeof z) => z.ZodType } = JsonObject,
   TActionInput extends JsonObject = TInputSchema extends z.ZodType<
     any,
     any,
     infer IReturn
   >
     ? IReturn
+    : TInputSchema extends { [key in string]: (zImpl: typeof z) => z.ZodType }
+    ? Expand<{
+        [key in keyof TInputSchema]: z.infer<ReturnType<TInputSchema[key]>>;
+      }>
     : TInputParams,
   TActionOutput extends JsonObject = TOutputSchema extends z.ZodType<
     any,
@@ -67,6 +160,10 @@ export const createTemplateAction = <
     infer IReturn
   >
     ? IReturn
+    : TOutputSchema extends { [key in string]: (zImpl: typeof z) => z.ZodType }
+    ? Expand<{
+        [key in keyof TOutputSchema]: z.infer<ReturnType<TOutputSchema[key]>>;
+      }>
     : TOutputParams,
 >(
   action: TemplateActionOptions<
@@ -75,23 +172,23 @@ export const createTemplateAction = <
     TInputSchema,
     TOutputSchema
   >,
-): TemplateAction<TActionInput, TActionOutput> => {
-  const inputSchema =
-    action.schema?.input && 'safeParseAsync' in action.schema.input
-      ? zodToJsonSchema(action.schema.input)
-      : action.schema?.input;
-
-  const outputSchema =
-    action.schema?.output && 'safeParseAsync' in action.schema.output
-      ? zodToJsonSchema(action.schema.output)
-      : action.schema?.output;
+): TemplateAction<
+  TActionInput,
+  TActionOutput,
+  TInputSchema extends { [key in string]: (zImpl: typeof z) => z.ZodType }
+    ? 'v2'
+    : 'v1'
+> {
+  const { inputSchema, outputSchema } = parseSchemas(
+    action as TemplateActionOptions<any, any, any>,
+  );
 
   return {
     ...action,
     schema: {
       ...action.schema,
-      input: inputSchema as TInputSchema,
-      output: outputSchema as TOutputSchema,
+      input: inputSchema,
+      output: outputSchema,
     },
   };
-};
+}

plugins/scaffolder-node/src/actions/types.ts

@@ -21,8 +21,10 @@ import { TaskSecrets } from '../tasks';
 import { TemplateInfo } from '@backstage/plugin-scaffolder-common';
 import { UserEntity } from '@backstage/catalog-model';
 import { Schema } from 'jsonschema';
-import { BackstageCredentials } from '@backstage/backend-plugin-api';
-
+import {
+  BackstageCredentials,
+  LoggerService,
+} from '@backstage/backend-plugin-api';
 /**
  * ActionContext is passed into scaffolder actions.
  * @public
@@ -30,77 +32,143 @@ import { BackstageCredentials } from '@backstage/backend-plugin-api';
 export type ActionContext<
   TActionInput extends JsonObject,
   TActionOutput extends JsonObject = JsonObject,
-> = {
-  // TODO(blam): move this to LoggerService
-  logger: Logger;
-  /** @deprecated - use `ctx.logger` instead */
-  logStream: Writable;
-  secrets?: TaskSecrets;
-  workspacePath: string;
-  input: TActionInput;
-  checkpoint<T extends JsonValue | void>(opts: {
-    key: string;
-    fn: () => Promise<T> | T;
-  }): Promise<T>;
-  output(
-    name: keyof TActionOutput,
-    value: TActionOutput[keyof TActionOutput],
-  ): void;
+  TSchemaType extends 'v1' | 'v2' = 'v1',
+> = TSchemaType extends 'v2'
+  ? {
+      logger: LoggerService;
+      secrets?: TaskSecrets;
+      workspacePath: string;
+      input: TActionInput;
+      checkpoint<T extends JsonValue | void>(opts: {
+        key: string;
+        fn: () => Promise<T> | T;
+      }): Promise<T>;
+      output(
+        name: keyof TActionOutput,
+        value: TActionOutput[keyof TActionOutput],
+      ): void;
+      /**
+       * Creates a temporary directory for use by the action, which is then cleaned up automatically.
+       */
+      createTemporaryDirectory(): Promise<string>;
 
-  /**
-   * Creates a temporary directory for use by the action, which is then cleaned up automatically.
-   */
-  createTemporaryDirectory(): Promise<string>;
+      /**
+       * Get the credentials for the current request
+       */
+      getInitiatorCredentials(): Promise<BackstageCredentials>;
 
-  /**
-   * Get the credentials for the current request
-   */
-  getInitiatorCredentials(): Promise<BackstageCredentials>;
+      /**
+       * Task information
+       */
+      task: {
+        id: string;
+      };
 
-  /**
-   * Task information
-   */
-  task: {
-    id: string;
-  };
+      templateInfo?: TemplateInfo;
 
-  templateInfo?: TemplateInfo;
+      /**
+       * Whether this action invocation is a dry-run or not.
+       * This will only ever be true if the actions as marked as supporting dry-runs.
+       */
+      isDryRun?: boolean;
 
-  /**
-   * Whether this action invocation is a dry-run or not.
-   * This will only ever be true if the actions as marked as supporting dry-runs.
-   */
-  isDryRun?: boolean;
+      /**
+       * The user which triggered the action.
+       */
+      user?: {
+        /**
+         * The decorated entity from the Catalog
+         */
+        entity?: UserEntity;
+        /**
+         * An entity ref for the author of the task
+         */
+        ref?: string;
+      };
 
-  /**
-   * The user which triggered the action.
-   */
-  user?: {
-    /**
-     * The decorated entity from the Catalog
-     */
-    entity?: UserEntity;
-    /**
-     * An entity ref for the author of the task
-     */
-    ref?: string;
-  };
+      /**
+       * Implement the signal to make your custom step abortable https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+       */
+      signal?: AbortSignal;
 
-  /**
-   * Implement the signal to make your custom step abortable https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
-   */
-  signal?: AbortSignal;
+      /**
+       * Optional value of each invocation
+       */
+      each?: JsonObject;
+    }
+  : /** @deprecated **/
+    {
+      // TODO(blam): move this to LoggerService
+      logger: Logger;
+      /** @deprecated - use `ctx.logger` instead */
+      logStream: Writable;
+      secrets?: TaskSecrets;
+      workspacePath: string;
+      input: TActionInput;
+      checkpoint<T extends JsonValue | void>(opts: {
+        key: string;
+        fn: () => Promise<T> | T;
+      }): Promise<T>;
+      output(
+        name: keyof TActionOutput,
+        value: TActionOutput[keyof TActionOutput],
+      ): void;
 
-  /**
-   * Optional value of each invocation
-   */
-  each?: JsonObject;
-};
+      /**
+       * Creates a temporary directory for use by the action, which is then cleaned up automatically.
+       */
+      createTemporaryDirectory(): Promise<string>;
+
+      /**
+       * Get the credentials for the current request
+       */
+      getInitiatorCredentials(): Promise<BackstageCredentials>;
+
+      /**
+       * Task information
+       */
+      task: {
+        id: string;
+      };
+
+      templateInfo?: TemplateInfo;
+
+      /**
+       * Whether this action invocation is a dry-run or not.
+       * This will only ever be true if the actions as marked as supporting dry-runs.
+       */
+      isDryRun?: boolean;
+
+      /**
+       * The user which triggered the action.
+       */
+      user?: {
+        /**
+         * The decorated entity from the Catalog
+         */
+        entity?: UserEntity;
+        /**
+         * An entity ref for the author of the task
+         */
+        ref?: string;
+      };
+
+      /**
+       * Implement the signal to make your custom step abortable https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal
+       */
+      signal?: AbortSignal;
+
+      /**
+       * Optional value of each invocation
+       */
+      each?: JsonObject;
+    };
 
 /** @public */
 export type TemplateAction<
   TActionInput extends JsonObject = JsonObject,
   TActionOutput extends JsonObject = JsonObject,
+  TSchemaType extends 'v1' | 'v2' = 'v1',
 > = {
   id: string;
   description?: string;
@@ -110,5 +178,7 @@ export type TemplateAction<
     input?: Schema;
     output?: Schema;
   };
-  handler: (ctx: ActionContext<TActionInput, TActionOutput>) => Promise<void>;
+  handler: (
+    ctx: ActionContext<TActionInput, TActionOutput, TSchemaType>,
+  ) => Promise<void>;
 };

plugins/scaffolder-node/src/actions/util.ts

@@ -18,6 +18,10 @@ import { InputError } from '@backstage/errors';
 import { isChildPath } from '@backstage/backend-plugin-api';
 import { join as joinPath, normalize as normalizePath } from 'path';
 import { ScmIntegrationRegistry } from '@backstage/integration';
+import { TemplateActionOptions } from './createTemplateAction';
+import zodToJsonSchema from 'zod-to-json-schema';
+import { z } from 'zod';
+import { Schema } from 'jsonschema';
 
 /**
  * @public
@@ -124,3 +128,60 @@ function checkRequiredParams(repoUrl: URL, ...params: string[]) {
     }
   }
 }
+
+const isZodSchema = (schema: unknown): schema is z.ZodType => {
+  return typeof schema === 'object' && !!schema && 'safeParseAsync' in schema;
+};
+
+const isNativeZodSchema = (
+  schema: unknown,
+): schema is { [key in string]: (zImpl: typeof z) => z.ZodType } => {
+  return (
+    typeof schema === 'object' &&
+    !!schema &&
+    Object.values(schema).every(v => typeof v === 'function')
+  );
+};
+
+export const parseSchemas = (
+  action: TemplateActionOptions,
+): { inputSchema?: Schema; outputSchema?: Schema } => {
+  if (!action.schema) {
+    return { inputSchema: undefined, outputSchema: undefined };
+  }
+
+  if (isZodSchema(action.schema.input)) {
+    return {
+      inputSchema: zodToJsonSchema(action.schema.input) as Schema,
+      outputSchema: isZodSchema(action.schema.output)
+        ? (zodToJsonSchema(action.schema.output) as Schema)
+        : undefined,
+    };
+  }
+
+  if (isNativeZodSchema(action.schema.input)) {
+    const input = z.object(
+      Object.fromEntries(
+        Object.entries(action.schema.input).map(([k, v]) => [k, v(z)]),
+      ),
+    );
+
+    return {
+      inputSchema: zodToJsonSchema(input) as Schema,
+      outputSchema: isNativeZodSchema(action.schema.output)
+        ? (zodToJsonSchema(
+            z.object(
+              Object.fromEntries(
+                Object.entries(action.schema.output).map(([k, v]) => [k, v(z)]),
+              ),
+            ),
+          ) as Schema)
+        : undefined,
+    };
+  }
+
+  return {
+    inputSchema: action.schema.input,
+    outputSchema: action.schema.output,
+  };
+};

plugins/scaffolder-node/src/alpha/index.ts

@@ -34,7 +34,7 @@ export * from './globals';
  * @alpha
  */
 export interface ScaffolderActionsExtensionPoint {
-  addActions(...actions: TemplateAction<any, any>[]): void;
+  addActions(...actions: TemplateAction<any, any, any>[]): void;
 }
 
 /**