Keep the template and rules together
A form consists of a DOCX with tagged content controls and a FormDefinition JSON file. Keep both together. Fields have distinct IDs and tags, labels, types and optional validation rules. Repeated controls sharing a tag receive the same answer.
| Type | Rules |
|---|---|
| Text / multiline | Optional maximum length; multiline permits line breaks. |
| Basic address syntax check. | |
| Number | Finite numeric answer and inclusive minimum/maximum. |
| Date | Valid calendar date in YYYY-MM-DD form. |
| Choice | One exact choice from the supplied list. |
| Checkbox | Boolean; a required checkbox must be true. |
Blank values are null. Required answers may remain empty in a draft. Read-only rules prevent changes through the form but include existing answers in completion.
Fill and complete through the SDK
import { openDocument } from "@onodocs/sdk";
import { createForm } from "@onodocs/sdk/forms";
const document = await openDocument(templateBytes);
try {
const form = createForm(document, definition);
await form.fill({ name: "Alex Morgan", quantity: 2 });
const { bytes, answers } = await form.complete();
await submitRequest(bytes, answers);
} finally {
document.dispose();
}Supply trusted template bytes and rules; the answer IDs above must exist in your definition. fill validates a batch before changing it. complete requires all required answers and returns document bytes and answers from the same snapshot. Catch FormValidationError and show its issues beside the relevant fields.
Embed the filling interface
import { openForm } from "@onodocs/editor/forms";
const view = await openForm({
container, input: templateBytes, definition,
persist: bytes => saveDraft(bytes),
onComplete: ({ bytes, answers }) => submitRequest(bytes, answers)
});The interface shows labelled inputs beside a read-only document preview. Focus follows the selected field. await view.save() saves an incomplete draft; await view.complete() validates, persists and submits. Supply your storage and submission callbacks and call view.dispose() on unmount. Scope recovery storage to the user, template and definition revision and ask before restoring.
Author a form
Use createFormDesigner({ container }) and await designer.open(bytes, definition). Add answer paragraphs, wrap ordinary selected paragraphs, or bind existing tags. Rule changes and document edits share Undo/Redo. designer.save() returns matching { bytes, definition }; persist both. Removing a field rule leaves its document content.
These controls implement application policy, not DOCX encryption. Validate submissions against your trusted rules and authorization. Locked, bound or structurally complex regions may not support ordinary text replacement.
Try the equipment-request form. The sample saves drafts in the current browser and downloads completed Word and answers JSON; it does not submit to a company service.