You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/docs/platform/workflow/build-a-workflow.mdx
+80Lines changed: 80 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -96,3 +96,83 @@ After you've tested your workflow in the **Development** environment, you can pr
96
96
97
97
</Step>
98
98
</Steps>
99
+
100
+
## Manage payload schema
101
+
102
+
The Payload Schema in Novu allows you to define, manage, and validate the structure of incoming data for each workflow. By creating a schema, you ensure that dynamic payloads sent to workflows are predictable, type-safe, and consistent across environments.
103
+
104
+
<Callout>Novu’s payload schema is based on the [JSON Schema](https://json-schema.org/) standard.</Callout>
105
+
106
+
With a defined schema in place, you can:
107
+
- Prevent unexpected runtime errors caused by invalid or missing data.
108
+
- Build reliable conditional logic using type-aware operators.
109
+
- Generate accurate previews powered by intelligent mock data.
110
+
- Enable autocomplete suggestions when referencing payload variables.
111
+
112
+
The schema acts as a contract between your systems and Novu, ensuring that every payload sent into your workflow conforms to expected rules. It provides your team with clear visibility into which variables exist, how they’re structured, and what validations are applied.
113
+
114
+
Payload schemas are especially useful when building complex workflows that rely on dynamic content, reusable blocks, or strict validation requirements.
115
+
116
+
### Define workflow schema
117
+
118
+
You can define the expected payload schema in three ways: manually, by importing a JSON sample, or by creating inline variables. When adding or editing a schema property, you can mark it as required.
119
+
120
+
<Callout>
121
+
If a property is marked as required, then it must be included in the payload when triggering the workflow using `novu.trigger()`.
122
+
</Callout>
123
+
124
+
#### Add Schema properties manually
125
+
126
+
You can manually define each property in your payload by specifying:
Each property you define becomes part of the payload schema, and helps Novu suggest accurate variables when configuring channels steps or digest actions.
131
+
132
+
#### Import from JSON
133
+
134
+
If you already have a sample payload, then you can quickly define the schema by importing it as a JSON object. Novu infers property names, types, and structures for you.
135
+
136
+
#### Create an inline variable
137
+
138
+
When referencing a variable that doesn’t exist in the schema (for example, `payload.title`) while editing a workflow step, follow these steps:
139
+
- Novu will prompt you to create the variable inline.
140
+
- Click Insert to add the variable to your schema with a default type of string.
141
+
- (Optional) After insertion, edit the variable in the manage schema tab. You can:
142
+
- Changing its type.
143
+
- Marking it as required.
144
+
- Adding validation rules.
145
+
146
+
### Enforce schema validation
147
+
148
+
Schema validation is enabled on a per-workflow basis. When active, Novu validates incoming payloads against the schema when the workflow is triggered.
149
+
150
+
This means:
151
+
- Missing required properties will cause the request to fail.
152
+
- Data types must match exactly. For example, a string cannot be passed where a number is expected.
153
+
- Invalid values are rejected before the workflow executes.
154
+
155
+
This validation is applied at the HTTP trigger level, and prevents invalid data from entering the workflow entirely.
156
+
157
+
### Schema configuration options
158
+
159
+
When defining a schema property, the available configuration fields vary depending on the selected type.
160
+
161
+
#### General fields (for all types)
162
+
163
+
- Property name
164
+
- Property type
165
+
- Required property checkbox
166
+
- Default value – Optional fallback if no value is provided
167
+
- Min length and max length
168
+
169
+
#### Type-specific configuration
170
+
171
+
Depending on the selected type, additional configuration options appear:
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?v=4&size=40){kind=avatar}
0 commit comments