Skip to content

Domains, drafts and domain editors

A domain is one business area with its own doctypes and its own data. You build a domain in a draft: a private work area whose name starts with _. Inside a draft you change definitions freely. When the model is ready, you publish it under its real name. Facet then creates the live domain and drops the draft.

Open a draft when you design a new domain, or when you change a live domain and want to test first. The draft is also where co-editors work with you: everyone who edits the draft keeps the right to edit the published domain.

  • The editor role. It lets you open a draft. Facet records you as the first domain editor of that draft.
  • Edit rights on the live domain to fork it into a draft. Use the Edit existing domain action in the Builder.
  • An administrator for co-editors. An administrator lists co-editors on the Editors tab of a domain. You cannot add co-editors yourself.

In the Builder, create a new draft. Facet generates the name; it always starts with _. Set the two name fields at once:

Field Rule Purpose
Name Lowercase letters, digits, and dashes. Starts with a letter. The name of the live domain you plan to publish.
Label Free text, up to 64 characters. The name people see in the interface.

Create the doctypes of your model (see Designing doctypes). Inside a draft, Facet relaxes the version rules: you can remove a field, change a type, or skip a version. All other schema checks still run, and every script must compile.

The definition cache updates a second or two after you save. Re-test a change after a short wait before you judge it.

Open a preview session from the draft. Facet then shows the draft in the live application: you open pages, run actions, and create documents, all inside the draft. Cross-domain references into live domains show no data during preview.

Open the Check tab. Facet lists the issues and notices for every doctype in the draft. An empty draft reports that there is nothing to publish. Fix the issues before you publish (see Checking a domain before publish).

Open the publish confirmation. You choose the target name and the mode:

  • Fresh publish — the target name must be free. Facet creates the domain and copies your doctypes.
  • Overwrite publish — the target domain exists. For every doctype you changed, the schema version must be exactly one above the live version, with a migration entry for the gap (see Evolving a schema).

Facet copies the co-editors to the published domain, files any cross-domain grant tickets, and drops the draft. Publish re-validates the model: the composition graph must close, and the overwrite version gate must pass.

Open a draft Open a draft

The call below publishes a draft to a fresh domain named orders. Read the API key from the FACET_API_KEY environment variable.

Terminal window
curl -k -X POST "https://facet.localhost:3443/Api/core/Domain/_3fjqk2m8p1xz/publish" \
-H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_name": "orders", "overwrite": false}'

The response names the published domain and reports any grant tickets and warnings. -k skips the certificate check of the local development address.

The name must be lowercase letters, digits, and dashes, and it must start with a letter. A name that starts with _ is a draft name. Fix the Name field or the target name and publish again.

The live version and your draft version differ by more than one, or a migration entry is missing. Raise the version one step at a time, or publish to a fresh domain instead.

The definition cache updates a second or two after a save. Wait briefly and test again.

Deleting a domain is an administrator action, and Facet refuses while one of its drafts is open. Discard the draft first.