Schemas

Schemas are central to Swirls. They define the shape of data at graph boundaries (trigger payloads, form submissions) and between nodes. Schemas power input validation, type-safe data flow, and TypeScript code generation for your application.

Why schemas matter

• Validation: Every trigger payload and form submission is validated against its schema before execution begins. Invalid data is rejected, so graphs always receive well-formed input.
• TypeScript code generation: The CLI generates Zod schemas and a typed form registry from your project's schemas. Your app gets full type safety and autocomplete when using the SDK or API.
• Predictable data flow: When nodes are connected by edges, the downstream node automatically inherits the output schema of the upstream node as its input schema. This keeps the graph's data contract explicit and consistent.
• Embeddable forms: Forms store a schema that the headless SDK uses for rendering and validation. Generated types keep your React code in sync with the form definition.

Where schemas are used

Forms

When you create a form in the Portal or via the API, you define its schema as a JSON Schema object. This schema determines what fields and validation rules apply when the form is submitted. The same schema is used for TypeScript code generation and SDK form adapters.

Triggers

A trigger is configured with a payload schema that defines the expected input. For form triggers, the schema comes from the linked form. For webhook triggers, you define the expected request body shape. Submissions and incoming requests are validated against the schema before the graph runs.

Nodes

Nodes can declare input and output schemas. When you connect nodes with edges, the downstream node's input schema is automatically derived from the upstream node's output schema. You only need to set an output schema explicitly when a node transforms data into a different shape.

Reusable schemas

You can create standalone schema objects in the Builder and reference them across forms, triggers, and nodes. This is useful when multiple resources share the same data shape.

TypeScript code generation

Use the CLI to generate TypeScript code from your project's form schemas:

1. Define forms (and their schemas) in the Portal or via the API.
2. Run swirls form gen to generate Zod schemas, a form registry, and module augmentation.
3. Use useSwirlsFormAdapter in your app with full type safety. Form names and field shapes are inferred from the generated code.

See TypeScript generation for setup details and Code generation for integration examples.

Best practices

• Define schemas at boundaries. Use schemas for trigger payloads and form submissions so every graph run starts with validated input.
• Let inheritance do the work. When you connect nodes with edges, rely on automatic input schema inheritance from upstream nodes. Only set an explicit input schema when you need a different contract.
• Regenerate after changes. When you add or change forms or schemas in the Portal, run swirls form gen again so your app's types stay in sync.
• Use JSON Schema. Swirls uses the JSON Schema specification for schemas. Use it for validation rules, required fields, and types so the system, generated code, and SDK stay consistent.

Schemas are the foundation for type-safe workflows and a type-safe integration experience. Define them early and the rest of the stack (validation, execution, SDK) stays predictable.