Forms (developer surface)
The platform's forms module renders dynamic forms from JSON schema with validation, conditional fields, and webhook submission.
What you'll learn
- The forms model (schema + UI hints + workflow)
- How to embed a form in your app
- How to receive submissions
Forms model
A form has three parts:
schema: # JSON Schema for field types & validation
type: object
properties:
email: { type: string, format: email }
reason: { type: string, enum: [bug, feature, question] }
details: { type: string, minLength: 10 }
required: [email, reason]
uiHints: # rendering hints
email: { widget: emailInput, label: 'Your email' }
reason: { widget: radioGroup, label: 'What kind of feedback?' }
details: { widget: textarea, rows: 5 }
submitWorkflow: # what happens on submit
- action: ticket.create
- action: webhook.fire
url: https://your-system.example.com/feedback-received
Authoring a form
- Web UI: Forms → New Form (drag-and-drop builder)
- As code:
createFormGraphQL mutation
Embedding
<script src="https://cdn.burdenoff.com/forms-embed.js"></script>
<div data-burdenoff-form="<form-id>"></div>
Or via React component from @burdenoff/sdk-node/forms.
Receiving submissions
Three ways:
| Mechanism | Use when |
|---|---|
Submission event (form.submitted) on the event bus | You're a service module |
| Webhook | You're outside the platform |
GraphQL polling (formSubmissions) | You want a UI dashboard |
Next steps
- Webhooks
- User guide — end-user form filling and submission