Domains and isolation
A domain holds one business area, such as hr or sales. Doctypes, hooks,
and grants all live inside it. Nothing crosses the boundary on its own.
Every cross-domain flow needs an explicit consent.
Explanation
Section titled “Explanation”What a domain holds. A domain is a core.Domain document, and its id
is the domain name. Every doctype id is therefore qualified, like
hr.Employee. The domain must exist before you register doctypes inside
it; registration answers 422 when it does not.
The domain owns its doctypes and their view templates. It owns the hooks
declared on the domain document, and the grants it issues to other domains.
It also owns its draft state: a draft domain has an id that starts with
_. You publish a draft into a fresh, live domain. Grants never involve
drafts — both sides must be live domains.
A domain moves as one unit. A domain is also the unit of portability. Export and import move one domain with its definitions and its data.
Isolation is the default. Data does not leave a domain on its own. A cross-domain read needs one of two explicit consents:
-
The document API. Reads follow role permissions. The role must hold a permission line that names the foreign doctype.
-
The automation surfaces. Replication fields, hooks with a foreign source, and Lua reads of a foreign doctype need an active domain grant. Without coverage, the read is refused.
Same-domain edges skip every gate. A domain reading itself is not a sharing decision.
What a grant shares. A grant is a document under the producer domain, and one grant covers one consumer domain. It carries a resources list: one entry per producer doctype, and each entry names field tags. Grants give read access only — no write access exists.
A field is shared when its tags match. Untagged fields count as
default, so an entry that namesdefaultreaches every untagged field. The consumer receives the covered fields only; the server removes the rest before delivery.The producer decides activation. Activation is the producer’s right, and it is all-or-nothing per grant. A publish that widens the shared resources drops an active grant back to inactive. The producer must accept it again.
One hop only. Replication is one hop. A replica field may not feed another replica; the authoring gate rejects the chain with
422.
The trade-off
Section titled “The trade-off”Grants couple domains. The consumer reads live data, so it depends on the producer’s contract. Deactivate the grant, and the copies stop updating. Narrow the tags, and the values already copied stay where they are. No job sweeps them out. Activate the grant again, and the next source event re-pushes the value.
Hard isolation costs duplication. Both options are first-class. When the coupling costs more than the copy, duplicate the field and keep the domains fully independent.
Related
Section titled “Related”- Architecture at a glance — where domains sit in the request path.
- Domains, drafts and domain editors — create a domain and register doctypes in it.
- Cross-domain replication — the copy mechanism a grant gates.
- Authorization enforcement — the role checks behind the document API.
- Internals on GitHub: doctype-system.md, domain-grants.md, replication.md.