Versioning
Templates change; documents do not change under you. How publishing and pinning work.
A template is edited continuously. A document, once created, must keep behaving the way it did when it was created — otherwise a deed drafted last quarter would re-render differently today.
DocDealer resolves that with immutable versions and pinning.
Publishing creates a frozen snapshot
A TemplateVersion is a lossless copy of everything that defines behaviour at publish time: content,
form schema, rules, the three sets of AI instructions, the word-format binding, category, locale,
tags, and the editability flag. Versions auto-increment per template.
Nothing about a published version can change afterwards. That is the guarantee documents rely on.
Documents pin a version
Creating a document without templateVersionId pins it to the template's latest published
version. A template with no published version returns 404 — there is nothing to pin to.
This is why editing a template does not disturb documents in flight. Publishing does not either: existing documents stay on the version they were created against until you deliberately move them.
Unpublished changes
The API exposes an unpublishedChanges flag on a template. It is derived on read, by hashing the
template's current editable surface and comparing it with the latest published version's stored hash.
No flag is stored on the row, which means it cannot drift — there is no bookkeeping step to forget.
Changelogs
On publish, the body-content differences against the previous published version are summarised into a changelog automatically. It describes what changed in the prose, which is the part a reviewer actually needs to see; schema and rule changes are visible in the diff of the snapshot itself.
Edit history is separate
Publishing is deliberate. History is automatic — a separate, time-based record captured as the collaborative editor saves, whether or not anything is published.
Consecutive edits by the same actor within about five minutes coalesce into one entry, so the timeline reads as editing sessions rather than keystrokes. Each entry records which areas changed — content, form, rules or metadata — and who changed them: a human editor, or an agent together with the admin who approved it.
The two mechanisms answer different questions:
| Versions | History | |
|---|---|---|
| Created by | Publishing, deliberately | The save loop, automatically |
| Purpose | What documents are pinned to | What happened, and who did it |
| Retention | Kept | Latest ~200 per template |
Both can be restored from, and both carry a snapshot of the collaborative editor state, so a restore is lossless rather than a re-paste of text.
What this means for an integration
- Pin explicitly if you care. Pass
templateVersionIdwhen creating a document if it must be built against a known version rather than whatever is latest. - Expect
404on an unpublished template. Publishing is the act that makes a template usable. - Treat
unpublishedChangesas advisory. It tells you a template has drifted from its last publish, which is useful to surface to an author, not something to gate an API call on.