Configuration#
Every output the model command produces is configured in one file,
model.toml, under a [tool.model] table. There are no command-line flags
for output: a language is generated exactly when its table is present.
Where the file is found#
model searches for model.toml in the model directory, then in each parent,
and takes the first one it finds. The search stops at a directory holding a
.git, so a stray model.toml above your project — in a home directory, say
— is never picked up. The Sphinx extension reads the same file the same way,
which is what keeps the docs and the CLI from disagreeing about one model.
Keys may be spelled with - or _ at any depth. pascal-case and
pascal_case are the same key. Keys that mean nothing to the generator are
ignored.
Languages#
At least one of [tool.model.go], [tool.model.go-client],
[tool.model.python], [tool.model.typescript], [tool.model.kotlin], or
[tool.model.postgres] must be present, or the build fails with an error.
Table |
Key |
Type |
Default |
Meaning |
|---|---|---|---|---|
|
|
path |
required |
Where to write the |
|
|
path |
required |
Where to write the |
|
path |
none |
Where to write a |
|
|
|
path |
required |
Where to write the |
|
string |
required |
The |
|
|
|
path |
required |
Where to write the |
|
string |
|
The text search configuration of every table’s search index, such as |
|
|
|
path |
required |
Where to write the |
|
string |
required |
The |
|
|
bool |
|
Export struct fields as PascalCase. Serialized keys do not change. Enum members are always |
|
|
|
path |
required |
Where to write the Go client’s |
|
string |
required |
The |
|
|
bool |
|
As |
Python takes out and nothing else, TypeScript out and svelte, and
Kotlin out and package. Every
path is relative to the directory you run model in.
[tool.model.python]
out = "generated/catalog.py"
[tool.model.typescript]
out = "src/catalog.mts"
[tool.model.postgres]
out = "schema/catalog.sql"
[tool.model.go]
out = "internal/catalog/catalog.go"
package = "catalog"
pascal-case = true
Go’s out is not free to sit anywhere. Generated fields are unexported unless
pascal-case is set, so the file has to be in the package that uses it. A
model with routes constrains it further: the generator type-checks the target
package to read your handler signatures, so out must sit in the package that
defines them. See Go.
Foreign models#
A [tool.model.foreign.<name>] table names a model that a ref may refer
into with model: <name>, as one naming a user refers into an auth server’s
model. See References into another model.
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
path |
required |
The foreign model’s directory, relative to this |
|
string |
none |
The import path of the foreign model’s |
|
string |
none |
The module the foreign model’s TypeScript output is imported as. Required when TypeScript output is enabled. |
|
string |
none |
The module of the foreign model’s Python output. Required when Python output is enabled. |
|
string |
none |
The package of the foreign model’s Kotlin output. Required when Kotlin output is enabled. |
Only the ${NAME} form is expanded: a bare $NAME is part of the path, and
there are no defaults or escapes. An unset variable fails the build, naming
it, rather than expanding to nothing. A relative expansion is still relative
to this model.toml; an absolute one, such as a Nix store path, is used as
it is.
[tool.model.foreign.auth]
path = "${MODEL_AUTH}/models"
go = "gitlab.com/terryp/model/auth/authapi"
typescript = "@omniblack/auth"
kotlin = "dev.omniblack.model.auth"
The flake’s auth-model package is the auth library’s models/ and its
model.toml, so a consumer’s dev shell, and any app that runs model, can
point MODEL_AUTH at it. The types then follow the consumer’s flake.lock;
its go.mod should require gitlab.com/terryp/model/auth at the same
revision. The flake’s wrk module,
wrkModules.default, sets it:
wrk = {
imports = [model.wrkModules.default];
model.auth.enable = true;
};
The TypeScript the foreign types are imported from is the flake’s
auth-typescript package, the npm package @omniblack/auth. It imports
@omniblack/model-runtime, so give pnpm-nix both, from the same revision:
pnpm-nix.lib.mkPackages pkgs {
"@omniblack/auth" = model.packages.${system}.auth-typescript;
"@omniblack/model-runtime" = model.packages.${system}.model-runtime;
};
The Kotlin is the flake’s auth-kotlin package, a Maven repository directory
holding dev.omniblack.model:auth. It depends on the runtime,
dev.omniblack.model:model-runtime, so read it beside the
kotlin-runtime package, from the same
revision. The same module sets MODEL_AUTH_KOTLIN beside
MODEL_KOTLIN_RUNTIME:
wrk = {
imports = [model.wrkModules.default];
model.auth.enable = true;
model.kotlin.enable = true;
model.kotlin.auth.enable = true;
};
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
maven { url = uri(System.getenv("MODEL_KOTLIN_RUNTIME")) }
maven { url = uri(System.getenv("MODEL_AUTH_KOTLIN")) }
mavenCentral()
}
}
// build.gradle.kts
dependencies {
implementation("dev.omniblack.model:auth:0.1.0")
}
Go qualifies a foreign type with the package its [tool.model.go-client]
declares, so the foreign model needs one when Go output is enabled.
Go features#
Go is the only language with opt-in features. Each one is enabled by mapping its name to the output version you want. Versioning lets a feature’s generated code change without breaking callers pinned to an older version.
[tool.model.go]
out = "internal/catalog/catalog.go"
package = "catalog"
[tool.model.go.features]
yaml = 1
postgres = 1
Feature |
Versions |
Emits |
Adds a dependency on |
|---|---|---|---|
|
|
JSON codecs on every struct. Always on; it cannot be turned off. |
— |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Fyne data binding, per-field validators, and time entry widgets. |
|
|
|
CRUD operations for every |
|
|
|
Enforcement of the model’s perms by the REST endpoints and routes, which then take an |
— |
|
|
Queries your users write of every |
— |
An unknown feature name, or a version a feature does not support, fails the build rather than being ignored.
Validate() is not a feature. Along with the JSON codecs it is always
emitted, in every language.
REST endpoints#
[tool.model.go.rest] generates a REST API for each top_level struct. Its
presence enables the endpoints, and it needs the postgres feature — without
it the build fails.
[tool.model.go.rest]
base-path = "/api"
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
string |
required |
Prefix every endpoint path is mounted under. Must start with |
Go REST endpoints covers what is generated.
Path roots#
[tool.model.go.roots] maps each path root a model uses to the Go function
that opens it, an opener in the package out sits in. Every root a
Go-generated path names must be in the table, or the build fails.
[tool.model.go.roots]
books = "OpenBooks"
epub = "OpenEpub"
Key |
Type |
Default |
Meaning |
|---|---|---|---|
a root name |
string |
— |
The opener’s name. It returns |
Like route handlers, openers are found by type-checking the target package, so
out must sit in the package that defines them. Path roots
covers what is generated.
Hooks#
Each [[tool.model.go.hooks]] entry names a Go function to run before a
top_level struct is created, saved, or deleted, or a file is uploaded to
one. If the function returns an
error, the write does not happen. Hooks need the postgres feature.
[[tool.model.go.hooks]]
event = "save"
func = "CheckBook"
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
|
— |
What the hook runs before: |
|
string |
— |
The function’s name. It takes an optional |
|
string |
none |
For an |
Like openers, hooks are found by type-checking the target package. Hooks covers what is generated.
Struct meta values#
Two keys name meta structs: struct YAML files, kept outside the model directory, whose type each struct’s own values must have. They suit data about a kind of record rather than about one record, such as an icon or a plural name.
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
path |
none |
The meta struct every struct declares |
|
path |
none |
The meta struct every |
Unlike out, these paths are relative to the model.toml that names them,
because they are inputs that sit beside the model.
[tool.model]
meta = "meta/ItemMeta.yaml"
top-level-meta = "meta/KindMeta.yaml"
The model loads the values and checks them against the meta struct’s constraints. A struct that is missing values, or that has values with no meta struct configured, fails the build. Each language generates the values as a constant of the meta struct type:
Python: a
ClassVar(Story.meta).TypeScript: a frozen property on the struct’s
const(Story.meta).Go: a method (
Story{}.Meta()), with aHasMetainterface to find the structs that have one. Fortop_level_meta, these areTopLevelMeta()andHasTopLevelMeta.
The automodel docs list each struct’s values beside its display name.
A meta struct’s fields must be strings, integers, booleans, enum members, or lists of these. The model-authoring guide has the full rules.
Extensions#
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
list of strings |
|
The installed extensions the model enables, by entry point name. |
[tool.model]
extensions = ["auth"]
An enabled extension lets the model’s types set the key it claims. See Extensions.
Documentation#
One key is read only by the Sphinx extension, never by the CLI:
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
list of |
|
Which parser reads each type’s |
It lives here rather than in conf.py so that one model has one answer. See
Documenting a model.
The command#
model [MODEL-PATH] [--install-skill]
Argument |
Meaning |
|---|---|
|
The model directory. Required, unless |
|
Write the bundled model-authoring guide to |
model prints one Generated <path> line per output and exits 0. It exits
2, with a message on standard error, when the path is missing, when
model.toml does not parse against the schema above, or when it configures no
language at all.
templates compile is not part of this command. It is a tool for people
working on the generators themselves, not for building a model.