Type safety

Using Knock you can get type safety between your codebase and the workflows that you trigger on Knock. By defining trigger data schemas for your workflows and generating types from them, you can catch integration errors at compile time and ensure your workflow triggers always include the correct data.

Before you can generate types for your workflow triggers, you need to define a JSON schema that describes the expected structure of the data passed to your workflow, which we call a trigger data schema. This schema serves as the source of truth for type generation.

You can set up trigger data validation in two ways:

Via the Workflow Builder:

1. Navigate to the "Trigger step" in the workflow builder
2. Under the "API params" section, click "Edit schema"
3. Supply a valid JSON schema that describes your trigger data
4. Commit your changes for the schema to take effect

Via the Management API or CLI:

• Use the trigger_data_json_schema field when creating or updating a workflow

Here's an example schema for a comment notification workflow:

Once you have trigger data schemas defined for your workflows, you can use the Knock CLI to generate type definitions for TypeScript, Python, Ruby, and Go.

This command will:

1. Fetch all workflows from your development environment that have trigger data schemas
2. Generate type definitions based on those schemas
3. Output the types to the specified file with the language inferred from the file extension

The target language is automatically determined by the file extension you specify:

• .ts - Generates TypeScript interface definitions
• .py - Generates Python class definitions using Pydantic
• .rb - Generates Ruby class definitions using dry-types
• .go - Generates Go struct definitions

The generated types provide compile-time safety when triggering workflows in your application code. Here's how to use them in each supported language:

Generated TypeScript interfaces can be imported and used with the Knock TypeScript SDK:

Generated Python classes use Pydantic for validation:

Generated Ruby classes use dry-types for type safety:

Generated Go structs include JSON tags for serialization: