Draft → publish
You do not edit the doctypes of a live domain directly. You open a draft, change the definitions there, and publish when the result is ready. Read this page to see what the draft state allows, and what publish checks before it commits.
Explanation
Section titled “Explanation”Two states. A domain carries a draft flag. A draft is a real domain
with an autogenerated name that starts with _. Facet keys every guard off
the flag, never off the prefix. Inside a draft:
-
the schema version may decrease or skip ahead,
-
destructive edits, such as field removal or a type change, are allowed at the same version,
-
a version bump needs no migration function,
-
everything else still validates: field names, action names, script compilation.
What publish does.
POST /Api/core/Domain/:id/publishpromotes the draft to a live domain. Publish is copy-and-drop, not a rename. The target gets fresh rows under its own name; the draft is then dropped. In overwrite mode the livecore.Domaindocument stays as it is: its description, its context sets and its hooks keep their live values, and a draft hook the live domain lacks comes back as a warning. Before it writes anything, publish checks that: -
the target name uses lowercase letters, digits and dashes, and starts with a letter. A leading
_answers422: that prefix is reserved for drafts, -
the source is a draft, read under a row lock,
-
the composition graph is closed — every
children:entry has a matchingmember_of, -
in fresh mode (
overwrite: false, the default), the target name is free. A name a live domain already holds answers409, -
in overwrite mode (
overwrite: true), the target name may already exist. Every doctype whose structure differs from the live one must carry aschema_versionof exactly the live version plus one, and a migration function for that gap; a gap without one answers422. A doctype with an identical structure passes without a version bump.Then, in one transaction, publish:
-
copies each doctype definition and its view templates,
-
relinks same-domain references to the new name,
-
in overwrite mode, converges the live view templates to the draft’s: a changed template is updated, a draft-only one is created, a live-only one is deleted. Saved collection views are never touched,
-
carries the draft’s editors over,
-
files domain-grant tickets when the definitions touch other domains,
-
drops the draft.
A crash before commit rolls back to an intact draft. You can retry the same publish.
What happens to documents. Publish never migrates live documents eagerly. They stay at their stored schema version. A lazy migration walks the chain on the next read. The version gate guarantees that every gap has a function, so the lazy walk cannot fail on a missing entry.
Draft data is scratch. Documents you create in the draft do not cross over — publish soft-deletes them with the draft. Only the structure publishes. A preview token lets you test first: it opens the standard routes for the draft’s documents, under your own identity.
The trade-off. The checks that guard live data do not run while you
edit. A version problem surfaces only at publish, when the gate rejects it,
and you return to the draft to fix it. A draft forked from a live domain does
not track that domain afterwards. The two can drift apart, and the comparison
happens only at publish time. Two states also mean two copies of a
definition. The live domain keeps serving its current definitions while you
edit the draft. Your changes reach other users only when you publish.
One more limit: replication stays inert in a draft. A draft domain never acts
as a replication source or consumer, so you cannot exercise a replicate
field before publish.
Related
Section titled “Related”- Build — the authoring trail from an empty draft to a live domain.
- Designing doctypes — how to declare fields and templates.
- Domains and isolation — what a domain bounds.
- Schema evolution — the version gate and lazy migration in depth.
- Internals on GitHub: draft-domains.md.