Skip to content
vyvy

Generating and distributing the configuration schema

The configuration schema is generated from Rust configuration types with Schemars. Schemars is a dev-dependencies entry, and the JsonSchema derives and generation code are limited to test builds.

Generate the schema

Section titled “Generate the schema”
Terminal window
cargo test --locked config::schema::export -- --ignored --exact

This updates config.schema.json at the repository root. Regenerate it when configuration types change, and commit the generated output. Regular tests check that the saved schema matches the configuration types.

Terminal window
cargo test --locked config::schema

Keybindings are declared to Schemars as strings or arrays of strings, and styles as strings. The promkit JSON and YAML settings use Schemars remote derives. Update the corresponding definitions when promkit adds or removes settings.

Distribute with cargo-dist

Section titled “Distribute with cargo-dist”

package.metadata.dist in Cargo.toml contains these distribution settings:

  • include: includes default.toml and config.schema.json in each binary archive.
  • extra-artifacts: runs the generation command above and also distributes both files as individual release assets.

dist-workspace.toml specifies cargo-dist 0.33.0, distribution targets, and shell and Homebrew installers. .github/workflows/release.yml is generated by dist generate; do not edit it manually. Schema bundling and individual assets use standard cargo-dist settings.

Terminal window
dist generate --check
dist plan --tag=v0.1.0

Pushing a version tag to GitHub builds and publishes a GitHub Release. To publish the Homebrew formula to ynqa/homebrew-tap, set the vy repository’s Actions secret HOMEBREW_TAP_TOKEN to a token with write access to the tap. Pull requests check only the distribution plan.

The #:schema directive in default.toml and the schema’s $id point to the same versioned release asset. When changing the release version, update the URL in default.toml and the example in Editor validation, then regenerate the schema.

The configuration’s version identifies the format and is independent of the release asset tag. Keep it unchanged for compatible additions and releases; update it for breaking changes that alter how existing settings are interpreted. At that point, review CONFIG_VERSION in src/config.rs, default.toml, and the policy for loading or migrating older formats, then regenerate the schema. Files without version are always treated as format 1.

Release schema URLs use this format:

https://github.com/ynqa/vy/releases/download/v<version>/config.schema.json