Skip to main content
Version: 0.11.0

Invowkmod Schema Reference

:::warning Alpha — Schema May Change The invowkmod schema is still evolving. Fields, types, and validation rules may change between releases as we stabilize the format. Always check the changelog when upgrading. :::

Complete reference for invowkmod.cue, the module metadata file. Module metadata is validated as a closed struct, so unknown fields cause a validation error.

Root Structure​

Every module must include an invowkmod.cue file with this structure:

#Invowkmod: {
    module:       string               // Required - module identifier
    version:      string               // Required - semver version (e.g., "1.0.0")
    description?: string               // Optional - module description
    author?:      string               // Optional - author or maintainer
    license?:     string               // Optional - SPDX license identifier
    repository?:  string               // Optional - canonical source URL
    requires?:    [...#ModuleRequirement] // Optional - dependencies
}

module​

Type: string (pattern: ^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*$) Required: Yes

The module identifier. It must match the folder name prefix (before .invowkmod).

module: "mytools"
module: "com.company.devtools"
module: "io.github.username.cli"

version​

Type: string (pattern: ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*)?$) Required: Yes

Module version in semver format (e.g., "1.0.0", "2.1.0-beta.1").

description​

Type: string Required: No

A short summary of the module's purpose.

author​

Type: string Required: No

Module author or maintainer (free-form text, typically "Name <email>" or organization name).

license​

Type: string Required: No

Module license using an SPDX identifier (e.g., "MIT", "Apache-2.0", "MPL-2.0").

repository​

Type: string (pattern: ^(https://|git@|ssh://)) Required: No

Canonical source URL for this module. Only https://, git@, and ssh:// schemes are accepted.

requires​

Type: [...#ModuleRequirement] Required: No

List of module dependencies from Git repositories.

requires: [
    {
        git_url: "https://github.com/example/common.invowkmod.git"
        version: "^1.0.0"
        alias: "common"
    },
]

ModuleRequirement​

Defines a single dependency entry:

#ModuleRequirement: {
    git_url: string
    version: string
    alias?:  string
    path?:   string
}

git_url​

Type: string Required: Yes

Git repository URL. Accepted forms: HTTPS (https://...), SSH shorthand (git@...), or SSH URI (ssh://...). The repository must contain a module.

version​

Type: string Required: Yes

Semantic version constraint used to resolve a Git tag.

alias​

Type: string Required: No

Overrides the default namespace for this dependency (must follow module naming rules).

path​

Type: string Required: No

Subdirectory within the repository that contains the module. Must be relative and cannot contain path traversal sequences.