Skip to content

Multi-file Schemas ​

(since 0.19.0) A .cstack schema no longer has to be one file. Three top-level directives cover two different jobs:

cstack
part "models/post.cstack"        // in a root: this file is more of me
part of "../schema.cstack"       // in a part: I belong to that root
import "../shared/common.cstack"  // anywhere: bring in a shared file's types

Each directive takes one line, a double-quoted path and nothing after it (no trailing comment). Directives may appear anywhere at top level; putting them first is the documented style. part, part of and import remain reserved words, so they still cannot name a model, field or any other identifier.

The decisions behind this page, with the alternatives that were rejected, are in ADR 0023.

Split one schema with part ​

The root is the file you point the macro or the CLI at. It lists its parts with part "<path>". Each part starts with part of "<path>", naming that root. Both halves must agree, and the error names both files when they do not.

The react-vite-swr example ships split this way. Its root:

cstack
datasource db {
  provider = "postgresql"
  url = env("DATABASE_URL")
}

auth Caller {
  id Int
}

part "schema/board.cstack"
part "schema/task.cstack"
part "schema/procedures.cstack"

and one of its parts, schema/task.cstack:

cstack
part of "../schema.cstack"

model Task {
  id Int @id
  title String
  done Boolean
  boardId Int
  board Board @relation(fields:[boardId],references:[id])

  @@allow("read", auth() != null)
  @@allow("create", auth() != null)
  @@allow("update", auth() != null)
  @@allow("delete", auth() != null)
}

Board is declared in schema/board.cstack and resolves here: a root and its parts share one flat namespace. A part is locked to its root. It is not a schema on its own, and a macro or command that is pointed at a part is refused (see Tooling for the one exception).

Parts are one level deep: a part cannot list parts of its own.

Share types with import ​

import is for a shape that several schemas use. The imported file belongs to nobody (it has no part of), so any number of schemas may import it. The shared-types-import example (since 0.19.1) is two services, billing and shipping, each with its own schema and its own SQLite database, importing one shared directory. The innermost file, shared/currency.cstack, has no directives at all:

cstack
// Shared by both services. It has no `part of`, so it belongs to no schema
// and any schema may import it. An imported file may declare only `type`,
// `enum` and `mixin`.

/// The currencies both services price in.
enum Currency {
  EUR
  USD
  XAF
}

shared/common.cstack imports it, and adds a type and a mixin:

cstack
// Shapes both services use. This file imports `currency.cstack` itself, so a
// schema that imports this file sees `Currency` too: imports are transitive.

import "currency.cstack"

/// An amount in the currency's minor unit (cents; whole francs for XAF).
type Money {
  amountMinor Int
  currency Currency
}

// The fields every service row carries. `@use(OrderRecord)` copies them into
// the importer's model, so each service stores them in its own table.
mixin OrderRecord {
  orderId Int
  createdAt DateTime @default(now())
}

The two service roots then reuse it. Billing's billing/schema.cstack:

cstack
datasource db {
  provider = "sqlite"
  url = env("DATABASE_URL")
}

import "../shared/common.cstack"

model Invoice {
  @use(OrderRecord)
  id Int @id
  customer String
  totalMinor Int
  currency Currency
  paid Boolean
}

and shipping's shipping/schema.cstack:

cstack
datasource db {
  provider = "sqlite"
  url = env("DATABASE_URL")
}

import "../shared/currency.cstack"
import "../shared/common.cstack"

enum ShipmentStatus {
  Pending
  InTransit
  Delivered
}

model Shipment {
  @use(OrderRecord)
  id Int @id
  destination String
  status ShipmentStatus
  insuredMinor Int
  insuredCurrency Currency
}

The imported declarations join the importer's single namespace. There is no as, show or hide. Three things are visible in the example:

  • Reuse. Both services import common.cstack. Each generates its own Currency and Money from the same file: different Rust types with the same variants, wire-compatible because they have the same shape.
  • Transitivity. Billing never imports currency.cstack, yet Invoice.currency is a Currency: billing gets it through common.cstack. check --list-files shows billing reaching currency.cstack only that way.
  • The diamond. Shipping imports currency.cstack directly (its Shipment uses Currency) and again through common.cstack. The loader keys files by canonical path, so the file is loaded once, whichever way each route spells the path.
text
$ cratestack check --schema examples/shared-types-import/billing/schema.cstack --list-files
schema OK: examples/shared-types-import/billing/schema.cstack
files (3):
  root        examples/shared-types-import/billing/schema.cstack
  import      examples/shared-types-import/shared/common.cstack
  import      examples/shared-types-import/shared/currency.cstack

$ cratestack check --schema examples/shared-types-import/shipping/schema.cstack --list-files
schema OK: examples/shared-types-import/shipping/schema.cstack
files (3):
  root        examples/shared-types-import/shipping/schema.cstack
  import      examples/shared-types-import/shared/currency.cstack
  import      examples/shared-types-import/shared/common.cstack

A name declared in two files is an error that names both.

A type is not a column

A type cannot be the type of a model column, so Money is not used by Invoice or Shipment above; it serves procedures and hand-written code (the example's src/lib.rs builds a Money for each service). Enums and mixins do reach the tables: each service stores Currency and the OrderRecord fields (orderId, createdAt) in its own table, with the same column definitions but no shared storage. orderId is the key that links one order across the two databases.

What an import may contain ​

An imported file, and every part of an imported root, may declare type, enum and mixin, plus the directives. A model, view, any kind of procedure, topic, query, extension and the root-only declarations are refused with an error that names the declaration and the import.

The reason is ownership. An imported model would create a table, routes and policies in every importer, so one shared file would couple several services' databases and migrations. Types, enums and mixins carry a shape and leave the storage to the importer: two services importing common.cstack each generate their own Money struct, wire-compatible because they have the same shape; an imported enum used by a model column is materialized in the importer's own migrations; a mixin's fields are copied into the importer's model by @use, as if they were written there. To split one schema's models across files, use part. Relaxing this rule later would be additive, so it ships in its narrow form first.

extension is refused too, on purpose: an extension unlocks syntax tied to a Cargo feature of the consuming crate, and a file someone else maintains must not switch a capability on in your build. A shared type that needs Vector(n) needs the importer to declare extension pgvector { }.

An imported file cannot be a part ​

An imported file may not declare part of. A part is locked to its root, and the import rule is how that lock is enforced: importing a file that says part of is refused with an error naming both files. Import a file that does not declare part of instead.

When to use which ​

part / part ofimport
Belongs toexactly one rootnobody; any number of schemas
May containanything a root may, except the root-only declarations belowtype, enum, mixin only
Use it tosplit one schema into filesshare value shapes between schemas

Where each declaration may go ​

DeclarationRootPartImported file, or a part of one
datasource, auth, transport, mcp { }yesnono
model, view, procedure, mutation procedure, subscription procedure, topic, queryyesyesno
extension <name> { }yesyes (merged by union)no
type, enum, mixinyesyesyes
part "…"yesnoin an imported root only
part of "…"noexactly oncein a part of an imported root
import "…"yesyesyes

datasource, auth, transport and mcp are root-only singletons: a part that declared one would make "which one wins" depend on file order.

Paths ​

  • A path is relative to the directory of the file that contains the directive. In schema/task.cstack, part of "../schema.cstack" names schema.cstack.
  • It must be relative, use / as its only separator, and end in .cstack.
  • The argument of include_*_schema! stays relative to CARGO_MANIFEST_DIR, and a CLI --schema stays relative to the working directory. Both name the root.
  • Every directive resolves against the directory of the canonical (real) path of the file that holds it, and .. is left to the operating system rather than folded first. A symlinked file therefore resolves its own part and import lines from where it really is, whichever spelling loaded it, and a symlinked part's part of is written relative to its real location.
  • The root is shown as you gave it; every other file is shown at its real location relative to the root's real directory, so a displayed path always names a file that exists.
  • Files outside the crate directory (import "../../shared/common.cstack") work inside a workspace. But cargo publish packages only the crate directory, so a published crate must keep its schema files inside it. This is the constraint include_str! has always had.

Load order ​

The order is defined and never depends on filesystem iteration. Nothing lists a directory.

  1. The root file.
  2. The root's parts, in the order of its part lines.
  3. For each file loaded in steps 1 and 2, in that order, each of its import lines in order: the imported file (its root, then its parts, then its imports, by the same rules), unless it was already loaded.

Declarations are merged by appending in load order, so the root's own declarations come first and adding an import never moves them. Mixins are expanded after the merge, so a model in one file can @use a mixin from another.

Splitting changes nothing ​

A split schema is the same schema. Its merged IR equals the IR of the same files concatenated in load order (with each part, part of and import line removed), ignoring source positions. Consequently:

  • generated Rust, Dart, TypeScript and WireMock output is unchanged: no generator reads a source position;
  • SCHEMA_SHA256 is unchanged, because it is a digest of the canonical IR, not of the text;
  • cratestack migrate diff against a committed snapshot produces nothing after a split. See Migrations.

To see it yourself, print the IR of the split root and of a hand-made concatenation without source positions, and diff them:

bash
cratestack print-ir --schema schema.cstack --no-spans > split.txt
cratestack print-ir --schema concatenated.cstack --no-spans > joined.txt
diff split.txt joined.txt   # no output

Rebuilds ​

SCHEMA_SOURCE keeps its type and meaning: it is the root file's text. A schema that spans more than one file additionally gets SCHEMA_FILES: &[(&str, &str)], a (path, contents) pair per file in load order, root first, each path relative to CARGO_MANIFEST_DIR. The macro takes every include_str! path from the canonical path it actually read, so absolute macro literals and symlinked roots work. Its include_str!s are what register every part and import, transitively, as rebuild dependencies of your crate. A single-file schema does not get SCHEMA_FILES, so its generated output is byte-identical to before.

Editing any listed file rebuilds. Adding a part works because listing it is an edit to the root, which is tracked; the macro re-expands and reads the new file. The one gap is stated, not hidden: a file that declares part of but that no root lists is not read by any build, so it is ignored. cratestack check and the editor report it when that file is checked or opened (see Tooling). If your new part's models do not exist, the root does not list it.

Errors you may see ​

Paths in messages are relative to the root file's directory and written with /, except where noted. Placeholders such as {part} stand for the real path or name. When an error involves two files, it also carries a related location: check --format json adds a related array (see Tooling) and editors show it as related information.

MessageCause and fix
`{part}` is listed as a part of `{root}`, but does not declare `part of`; add `part of "{back}"` to `{part}`The root lists a file that has no part of. Add the line the message gives.
`{part}` is listed as a part of `{root}`, but declares itself a part of `{other}`The part names a different root. Point part of at the root that lists it, or list the part from {other}.
`{part}` declares itself a part of `{root}`, but `{root}` does not list it; add `part "{rel}"` to `{root}`A part of file that no root lists. Add the part line to the root.
`{file}` is a part of `{root}`, not a schema root; point the macro or command at `{root}`A part was given where a root is required. Use the root. {file} is the part as you gave it and {root} is the root resolved against it, so both paths work as given. For --schema examples/react-vite-swr/schema/task.cstack the message names examples/react-vite-swr/schema.cstack.
`{kind}` belongs in the root schema (`{root}`), not in a partdatasource, auth, transport or mcp in a part. Move it to the root.
a part cannot list parts of its own; move `part "{path}"` to the root schema (`{root}`)Parts are one level deep. List the file from the root.
duplicate `part of` (first declared on line {n})Two part of lines in one file. Remove one.
`{path}` is already listed as a part on line {n}The root lists one file twice. Remove one line.
`{root}` lists itself as a partA root has a part line naming itself. Remove it.
cannot import `{file}`: it is a part of `{root}`, and a part is locked to its root; import a file that does not declare `part of` insteadAn import names a part. Import a shared file that has no part of.
import cycle: `{a}` → `{b}` → … → `{a}`Imports form a cycle, including a file importing itself. When the import line sits in a part, that step reads `{root}` (part `{part}`). Break the cycle at the import line the error points to.
`{kind} {name}` cannot come from an import: `{file}` is imported by `{importer}`, and an imported file may declare only `type`, `enum` and `mixin`; use `part` to split one schema across filesA model, view, procedure, topic, query or extension in an imported file. (For transport and mcp the message starts with `{kind}` alone.) Move it into the importer, or into a part.
`{name}` is declared twice: `{kind_a} {name}` in `{file_a}` (line {la}) and `{kind_b} {name}` in `{file_b}` (line {lb})One name in two files. Rename one. A repeat inside a single file keeps its single-file message.
cannot read `{path}` (listed on line {n} of `{file}`): {io error}A listed file is missing or unreadable. Fix the path or restore the file.
`{directive}` path `{path}` must be a relative path written with `/` and ending in `.cstack`An empty path, an absolute path, a backslash, or a missing .cstack suffix (a bare .cstack with no file name is refused too).
expected a quoted path after `{directive}`, like `{directive} "models/post.cstack"` A directive with no quoted path, an unterminated quote, or text after the closing quote.
`{file}` changed while it was being loaded; load it againA file was modified between two reads of the same load (rare race). Run the command or build again.
`{directive}` needs the schema to be loaded from a file, because "{path}" is resolved against that file's directory; use `parse_schema_file` or `cratestack check --schema <root>`A directive given to a text-only parser entry point (parse_schema, parse_schema_named and similar). Load from a file.

An unreadable root keeps its single-file message, failed to read schema file {path}: {error}.

The structural checks above, and every file's syntax, stop at the first error. After that, validation runs on the merged schema and reports every independent error in one run, including errors from several files. Splitting never turns a valid schema invalid: the loader refuses no pair of declarations that one concatenated file would accept.

Tooling ​

The CLI ​

Every command that takes --schema (check, print-ir, generate-dart, generate-typescript, generate-wiremock, migrate diff, migrate baseline, diff, contract) resolves the whole file graph. They take the root; given a part they fail with the "is a part of … not a schema root" error. check is the exception: given a part, it follows part of to the root, checks the whole schema, and says so:

text
$ cratestack check --schema schema/task.cstack
`schema/task.cstack` is a part of `schema.cstack`; checked the whole schema
schema OK: schema.cstack

If the root does not list the part, that is the "declares itself a part of … does not list it" error, with exit status 1. In --format json the payload keeps schema as given and adds "root" only when it differs.

check --list-files prints the resolved file set after schema OK: a files (N): line, then one role path line per file in load order, the role being root, part, import or import part (an imported root's part). For the react-vite-swr example:

text
$ cratestack check --schema schema.cstack --list-files
schema OK: schema.cstack
files (4):
  root        schema.cstack
  part        schema/board.cstack
  part        schema/task.cstack
  part        schema/procedures.cstack

With --format json it adds "files": [{ "path", "role" }]. Without the flag the output is unchanged. A diagnostic that involves a second file carries "related": [{ "file", "line", "start", "end", "message" }], only when there is one. The related locations are labelled `{kind} {name}` is declared here first, `{part}` is listed here, `{file}` declares `part of` here and `{file}` is imported here.

print-ir --no-spans prints the IR with every source position zeroed, the form two schemas are compared in (see Splitting changes nothing).

The editor ​

The language server follows the file graph. Diagnostics are attributed to the file they belong to, a part opened on its own is checked through its root, and go-to-definition and completion cross files (completion offers models, mixins, types, procedures and fields of the whole graph, not enum names). Rename is refused in a schema that spans more than one file, or in any file whose text has a part, part of or import line, and references are file-local. Closing a file without saving reverts the analysis to its disk text. All of it is described in Editor tooling.

Limits ​

These are deliberate, and each is additive to lift later:

  • no import … as ns, show or hide (today a parse error, so it is free to add);
  • no models, views or procedures through import;
  • no cross-file rename or find-references in the editor. Rename is refused rather than done halfway, but (since 0.19.1) it can only see importers inside the editor's workspace folders: an importer outside them, or a client that sends no workspace folders, cannot be seen, and a shared file with no directive of its own can then still be renamed;
  • no package or registry imports (import "@scope/pkg");
  • a build cannot detect an unlisted part of file.

The roadmap records why each is deferred and what unblocks it.

  1. ADR 0023: Multi-file Schemas
  2. Mixins, which an import may supply
  3. Editor tooling
  4. The shared-types-import example (since 0.19.1): two services importing one shared file

Released under the MIT License.