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

[tool.model.python]

out

path

required

Where to write the .py file.

[tool.model.typescript]

out

path

required

Where to write the .ts/.mts file.

svelte

path

none

Where to write a .svelte.ts module of Svelte classes, which imports out. See Svelte.

[tool.model.kotlin]

out

path

required

Where to write the .kt file. See Kotlin.

package

string

required

The package clause of that file.

[tool.model.postgres]

out

path

required

Where to write the .sql DDL.

search-config

string

simple

The text search configuration of every table’s search index, such as english. See Full-text search.

[tool.model.go]

out

path

required

Where to write the .go file.

package

string

required

The package clause of that file.

pascal-case

bool

false

Export struct fields as PascalCase. Serialized keys do not change. Enum members are always <Enum><Member>.

[tool.model.go-client]

out

path

required

Where to write the Go client’s .go file. See The Go client.

package

string

required

The package clause of that file.

pascal-case

bool

false

As [tool.model.go]’s.

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

path

required

The foreign model’s directory, relative to this model.toml. Each ${NAME} in it is replaced by the environment variable NAME, which must be set. It is loaded with the model.toml nearest it.

go

string

none

The import path of the foreign model’s [tool.model.go-client] package. Required when Go output is enabled.

typescript

string

none

The module the foreign model’s TypeScript output is imported as. Required when TypeScript output is enabled.

python

string

none

The module of the foreign model’s Python output. Required when Python output is enabled.

kotlin

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

1

JSON codecs on every struct. Always on; it cannot be turned off.

—

yaml

1

UnmarshalYAML/MarshalYAML on every struct.

gopkg.in/yaml.v3

toml

1

UnmarshalTOML/MarshalTOML on every struct.

github.com/pelletier/go-toml/v2

xml

1

FromXMLElement decoders.

github.com/beevik/etree

fyne

1

Fyne data binding, per-field validators, and time entry widgets.

fyne.io/fyne/v2

postgres

1

CRUD operations for every top_level struct.

github.com/jackc/pgx/v5

auth

1

Enforcement of the model’s perms by the REST endpoints and routes, which then take an mdl.Authorizer.

—

find

1

Queries your users write of every top_level struct, and over REST. Needs postgres. It is off by default because it makes a REST API accept arbitrary filters.

—

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

base-path

string

required

Prefix every endpoint path is mounted under. Must start with /; a trailing / is dropped.

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 (fs.FS, error), and takes an optional context.Context, then optionally the struct owning the path.

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

event

create, save, delete, or upload

—

What the hook runs before: Insert; Insert, Update, and Upsert; Delete; or storing a file field’s content.

func

string

—

The function’s name. It takes an optional context.Context, then a pointer to the struct, then for an upload hook the content as a []byte, and returns an error. A generic function over a union of structs runs for each of them.

field

string

none

For an upload hook, and only for one: the file field it runs for.

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

[tool.model] meta

path

none

The meta struct every struct declares meta values for.

[tool.model] top-level-meta

path

none

The meta struct every top_level struct declares top_level_meta values for. No other struct may declare them.

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 a HasMeta interface to find the structs that have one. For top_level_meta, these are TopLevelMeta() and HasTopLevelMeta.

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

[tool.model] extensions

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

[tool.model] docstring-parser-regexes

list of [pattern, parser]

[]

Which parser reads each type’s desc.

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

MODEL-PATH

The model directory. Required, unless --install-skill is given.

--install-skill

Write the bundled model-authoring guide to .claude/skills/authoring-models/SKILL.md in the current directory, then exit without generating anything.

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.