`module.toml` Manifest Reference

The module.toml file is the manifest at the root of every rescile module. It defines the module’s identity, declares the parameters it accepts, specifies the asset and input schemas it expects from the consuming project, and configures data generators that fetch or scaffold data automatically before the graph is built.

When a module is loaded via --module, rescile reads this file first to validate parameters, assets, and inputs before any graph processing begins. It also drives the bootstrap command and dependency resolution via rescile-ce mod.

[module]
name = "my-module"
version = "1.0.0"
description = "A custom module"
rescile_version = ">=0.1.85"

schemas = ["./schemas/infrastructure.schema.json"]

[dependencies.other_module]
url = "https://github.com/rescile/other.git"
resource_aliases = { "old_type" = "new_type" }

[params.env]
description = "Environment variable"
default = "dev"
required = false

[generators.fetch_data]
target_input = "config.json"
command = ["script.sh"]
env = ["TOKEN={{ env.TOKEN }}"]
ttl = "1h"
condition = "on_missing"

[generators.fetch_data.secrets.my_token]
collection = "my-app-secrets"
secret = "API_TOKEN"

`[module]` — Module Identity

Declares the module’s name, version, human-readable description, and the minimum rescile version it requires. These fields are displayed in the rescile dashboard and used during dependency resolution.

Key	Required	Description
`name`	Yes	A short identifier for the module (e.g., `"standard-webapp"`).
`version`	Yes	Semantic version string (e.g., `"1.0.0"`).
`description`	No	A human-readable summary shown in the module index.
`url`	No	Canonical URL of the module’s repository. Optional; may be omitted entirely — displayed in the dashboard and module index wherever present.
`rescile_version`	No	Version constraint (e.g., `">=0.1.210"`). Checked during both static workspace validation (`rescile-ce validate`) and graph build; fails fast if the running binary is incompatible.

For detailed usage see Using Modules.

`[dependencies]` — Module Dependencies

Declares other modules this module depends on. Supported declaration formats include:

A simple Git URL string: "https://github.com/rescile/core.git:v1.0.0"
A detailed Git table with ref constraint: { git = "...", tag = "..." }, { git = "...", branch = "..." }, or { git = "...", rev = "..." }
A semver constraint for Git release tags: { git = "...", version = "^1.2.0" }
A release archive with optional checksum: { url = "...", version = "..." } or { url = "https://example.com/mod.tar.gz", checksum = "sha256-..." }
A local path: { path = "../other-module" }

An optional resource_aliases map transparently remaps resource type names from the imported module to avoid naming conflicts in the global graph.

Dependency Key Naming and Slug Matching

The table key under [dependencies] serves as a parent-scoped alias. Keys must start with an ASCII alphanumeric character and contain only lowercase letters, digits, and hyphens ([a-z0-9][a-z0-9-]*):

[dependencies.landing-zone-module]
git = "https://github.com/rescile/landing-zone-module"

[dependencies.aws-provider-module]
git = "https://github.com/rescile/aws-provider-module"

Best practice is for the dependency key to match the slug generated from the dependency’s declared [module].name. When a dependency key differs from that generated slug, Rescile emits a warning:

WARN: Dependency key '<key>' in '<manifest>' resolves to module '<name>' whose generated slug is '<slug>'. This alias remains allowed, but may conflict with another dependency.

Dependencies are resolved recursively. Use rescile-ce mod lock to pin them to exact commits or checksums for reproducible builds.

For the full reference including lockfile commands, canonical Git source handling, and semver resolution see Module Dependencies & Lockfiles.

`[params]` — Module Parameters

Declares the named parameters a module accepts at runtime via --module-params. Each parameter entry can specify a description, a default value, whether it is required, and an allowed_values list for validation. Declared parameters are made available as {{ params.<name> }} in the Tera context of all models/, compliance/, output/, and actions/ files of the module.

For backward compatibility the same parameters are also still exposed as root-level template variables ({{ <name> }}). This legacy form works but emits a deprecation warning; new authoring should prefer {{ params.<name> }}.

Parameters are also exposed to action constraint templates as {{ params.<name> }} (for example, hostname:{{ params.runner_hostname }}) and returned in the /api/engine-info endpoint as module_params.

Merge semantics — parameters form one workspace-wide namespace, resolved before any module content is parsed:

--module-params values win; data/module_params.json fills only keys the CLI did not set.
Defaults from the local data directory’s module.toml come next — the concrete workspace overwrites every module default.
Module defaults are resolved by dependency topology: a module’s default overwrites the default of any module that (transitively) depends on it, so root/base modules win over the modules layered on top (e.g. ucs-base over salesforce). Overwritten defaults are noted only when debug selectors are active.
Defaults from modules with no dependency relation between them and different values, with no explicit value, fail the build with a message naming the modules and values; set an explicit value to resolve it. Identical defaults are fine. With an explicit value the importer warns and uses it.
Every module sees the fully-merged map, regardless of module order — a later module’s default also satisfies an earlier module’s required declaration.
allowed_values is validated for every value type: non-string values are matched against their canonical string form (number 3 matches "3").

Key	Description
`description`	Human-readable explanation of the parameter’s purpose.
`required`	Boolean. If `true`, rescile will error when the parameter is not supplied.
`default`	Fallback value used when the parameter is not supplied and `required` is `false`.
`allowed_values`	Array of permitted values, compared as strings. rescile validates the supplied value against this list.

For usage examples see The Data Directory — Parameters Make Modules Reusable.

Schema Declarations

Modules can bind their resources to central schemas. When schemas are bound, the validator checks required properties, relations, capability coverage, and CSV value conformance. See Schema Validation for the full validation behavior.

`schemas = [...]`

Load one or more schema sources for the whole module:

schemas = ["./schemas/infrastructure.schema.json"]

`[[schema]]`

Bind a schema to specific resources:

[[schema]]
schema = "./schemas/infrastructure.schema.json"
resources = ["virtual_machine", "network"]

`[[implements]]`, `[[requires]]`, `[[offers]]`

Declare how the module relates to a published schema:

[[implements]]
schema = "rescile/infrastructure"
version = "20260729"
resources = ["virtual_machine"]

[[offers]]
schema = "rescile/infrastructure"
resource = "virtual_machine"
verb = "provision"
action = "lxd-provision"

Per-asset override

Override the schema used for a single CSV asset:

[assets."virtual_machines.csv"]
schema = "./schemas/custom-vm.schema.json"

`[assets]` — Asset Import Directives

Deprecation notice: The legacy columns and bootstrap fields inside [assets] are deprecated. Define expectations with central schemas (see Schema Declarations) and ship starter CSV rows in the module’s assets/ directory instead, copying them with rescile-ce mod sync.

The following fields remain valid import-time directives with no schema equivalent: name_template, match_on, resource_type, schema, extends, description, and bootstrap_policy.

Declares import-time directives and optional per-asset schema overrides for CSV asset files. Each entry can set an explicit resource_type, a name_template that dynamically rewrites the primary key (name property), match_on rules that filter rows before they are imported, a per-asset schema override, a satellite extends marker, an optional description, and a bootstrap_policy that controls how starter CSV rows are merged into the workspace. The legacy columns validation table and bootstrap string are still parsed but should be replaced by central schemas and module starter files.

Field	Type	Description
`name`	string	The asset filename, e.g. `servers.csv`.
`resource_type`	string	Override the resource type inferred from the filename.
`name_template`	string	Tera template that produces the row primary key (`name`).
`match_on`	array	Filter rows before they are imported into the graph.
`schema`	string	Path or URL to a JSON schema that validates this asset.
`extends`	string	Satellite marker for a derived resource type.
`description`	string	Human-readable purpose.
`bootstrap_policy`	string	`once`, `append`, `merge` (default), `replace`, or `skip`.

For the modern approach see Bootstrapping a Project and Asset Management — Module Asset Configurations.

Shared asset types across modules: if two modules declare column specifications for the same asset file, startup fails with Asset '<file>' has conflicting column specifications ... Please use resource_alias to resolve the conflict. When your module merely references a type owned by another module (e.g. system, team), ship its reference CSV rows without an [assets."<file>"] block and declare expectations via schemas. See Composing Multiple Modules.

`[input]` — Input Schema & Bootstrap (Deprecated)

Deprecation notice: The [input] and [[inputs]] blocks are deprecated. Place starter JSON input files in the module’s input/ directory and copy them with rescile-ce mod sync. Central schemas can validate structure when needed.

Declares the JSON input files the module expects in the consuming project’s data/input/ directory. Each entry defines the expected format (currently object_of_objects), optional fields validation, and a legacy bootstrap string.

For the modern approach see Bootstrapping a Project and Input Management.

`[generators]` — Data Generators

Configures Phase 0 materialization of HTTP API data before the graph is built. Each generator references a reusable external/<name>.toml fetcher and specifies one target_input or target_asset.

[generators.catalog]
external = "catalog"
target_input = "catalog.json"
args = { region = "{{ params.region }}" }
condition = "on_missing"
abort_on_failure = true

Arguments support literals, module parameters, and environment values. Request details, secrets, pagination, and cache TTL belong to the external fetcher. Inline HTTP generators remain executable with a deprecation warning for the current major release. Command/script execution is unsupported; obsolete command fields remain parseable only to provide a focused migration error. Both legacy field sets will be removed in the next major release.

For the complete generator reference including security and validation behaviour see Data Generators.

`external/` — On-demand model inputs

external/ is a module directory, not a module.toml block. It contains named TOML HTTP fetchers used by model-header external! declarations. A model reference such as "external!" = "vendor_lookup" resolves external/vendor_lookup.toml in the same module.

External fetchers differ from generators:

generators run before asset loading and write files;
external fetchers run only for argument combinations reached by model rules and return in-memory JSON;
external fetchers are HTTP-only by schema and have no runtime field;
generators can reference the same fetchers to persist Phase 0 data;
external fetch failure is a hard graph-build error.

Fetcher files support sequential steps, GET/POST, GraphQL queries, headers, response chaining, pagination, JMESPath, TTL caching, and Vault secret declarations. With --offline, an exact-key cached response is used even when expired. If no compatible cache exists, the build fails without sending a request.

See Templating & Data — On-demand HTTP and GraphQL inputs.

module.toml Manifest Reference

module.toml Manifest Reference

[module] — Module Identity

[dependencies] — Module Dependencies

Dependency Key Naming and Slug Matching

[params] — Module Parameters

Schema Declarations

schemas = [...]

[[schema]]

[[implements]], [[requires]], [[offers]]