Modifying the CLI Manifest Schema
Use this skill when changing the Golem application manifest JSON schema under
cli/schema.golem.cloud/app/golem/ or when adding/removing manifest fields in
cli/golem-cli that must be reflected in schema validation and generated
template references.
Do not use this skill for the structured command output schema under
cli/golem-cli/command-output-schema/command-output.schema.json. For
StructuredOutput types, structured-output serializers, or command-output schema generators, use
modifying-cli-output-schema instead.
Core Rules
- Change the current manifest contract directly and update every in-tree parser, model, template,
example, fixture, test, schema reference, and generated application that consumes it.
- Do not add or preserve compatibility parsing, fallback defaults, upgrade paths, aliases,
deprecated fields, migrations, backfills, or support for older manifest versions.
- Edit the schema directory named by
manifest_schema_version!() unless release or schema-hosting
work requires a new publication identifier. A new directory is a publication decision, not a
compatibility mechanism.
- When a new schema identifier is required, copy the current directory, update its
$id, make it
the sole current schema reference, and apply the contract change there. Do not backfill
historical schema directories.
- If the YAML document version changes, update the CLI to accept the new current version rather
than keeping the previous version supported.
Important Terminology
- Manifest version: the version of the YAML document itself, exposed as
sdk::MANIFEST in cli/golem-cli/src/versions.rs.
- Manifest schema version: the version of the JSON schema under
cli/schema.golem.cloud/app/golem/<version>/golem.schema.json, exposed via
manifest_schema_version!() in cli/golem-cli/src/versions.rs.
These are NOT the same concept and do not have to move together.
Schema hosting may use development identifiers such as 1.6.0-dev.8 while the manifest document
uses a release-line identifier such as 1.6.0. Follow explicit release direction when choosing a
new publication identifier; do not invent a version bump merely to retain the old schema.
Workflow
- Read
cli/golem-cli/src/versions.rs and identify the schema directory named by
manifest_schema_version!().
- Modify that current schema in place, or create a new publication directory only when the task's
release/schema-hosting requirements call for one.
- Update the Rust manifest model and serde behavior so the implementation and JSON Schema describe
the same contract.
- Update
cli/golem-cli/src/versions.rs:
- change
sdk::MANIFEST only when the YAML document version changes;
- change
manifest_schema_version!() only when using a new schema publication identifier.
- If
sdk::MANIFEST changes, replace the old-version policy in
cli/golem-cli/src/app/manifest_version.rs with the new current contract. Do not keep previous
versions accepted or generate compatibility upgrades.
- Check every schema-version consumer, especially:
cli/golem-cli/src/lib.rs
cli/golem-cli/src/app/template/snippet.rs
cli/golem-cli/src/app/build/check/mod.rs
- tests containing embedded
$schema references
- Update all in-tree manifests, templates, examples, fixtures, tests, and generated artifacts that
use the changed field or version.
- Run focused validation, checks, and tests.
Things To Watch
- Do not assume
sdk::MANIFEST and manifest_schema_version!() should always match.
- When introducing a new field or enum value, ensure both serde parsing and JSON
schema validation agree.
- If the CLI emits manifest templates/snippets, make sure they reference the new
schema version.
- Historical schema directories are publication artifacts, not contracts that current CLI code
must continue accepting. Leave unrelated history untouched, but do not update it or route current
behavior through it.
Useful Files
cli/golem-cli/src/versions.rs
cli/golem-cli/src/lib.rs
cli/golem-cli/src/app/template/snippet.rs
cli/golem-cli/src/app/manifest_version.rs
cli/golem-cli/src/app/build/check/mod.rs
cli/golem-cli/src/model/app_raw.rs
cli/schema.golem.cloud/app/golem/*/golem.schema.json
Verification Checklist
- The current schema validates the changed manifest shape and rejects removed shapes.
- Serde parsing and JSON Schema validation agree.
- CLI version constants and emitted
$schema references point to the sole current contract.
- No compatibility parser, alias, old-version support, upgrade path, migration, or backfill was
added or retained for the changed contract.
- All in-tree manifests and generated examples use the current shape.
cargo check -p golem-cli passes.
- Focused manifest schema/version tests pass with
--report-time.
1---2name: modifying-cli-manifest-schema3description: "Changing the current application manifest JSON schema and aligning CLI schema references."4metadata:5 source: https://skillmd.com/skills/golemcloud/modifying-cli-manifest-schema6---78# Modifying the CLI Manifest Schema910Use this skill when changing the Golem application manifest JSON schema under11`cli/schema.golem.cloud/app/golem/` or when adding/removing manifest fields in12`cli/golem-cli` that must be reflected in schema validation and generated13template references.1415Do **not** use this skill for the structured command output schema under16`cli/golem-cli/command-output-schema/command-output.schema.json`. For17`StructuredOutput` types, structured-output serializers, or command-output schema generators, use18`modifying-cli-output-schema` instead.1920## Core Rules21221. Change the current manifest contract directly and update every in-tree parser, model, template,23 example, fixture, test, schema reference, and generated application that consumes it.242. Do not add or preserve compatibility parsing, fallback defaults, upgrade paths, aliases,25 deprecated fields, migrations, backfills, or support for older manifest versions.263. Edit the schema directory named by `manifest_schema_version!()` unless release or schema-hosting27 work requires a new publication identifier. A new directory is a publication decision, not a28 compatibility mechanism.294. When a new schema identifier is required, copy the current directory, update its `$id`, make it30 the sole current schema reference, and apply the contract change there. Do not backfill31 historical schema directories.325. If the YAML document version changes, update the CLI to accept the new current version rather33 than keeping the previous version supported.3435## Important Terminology3637- **Manifest version**: the version of the YAML document itself, exposed as38 `sdk::MANIFEST` in `cli/golem-cli/src/versions.rs`.39- **Manifest schema version**: the version of the JSON schema under40 `cli/schema.golem.cloud/app/golem/<version>/golem.schema.json`, exposed via41 `manifest_schema_version!()` in `cli/golem-cli/src/versions.rs`.4243These are NOT the same concept and do not have to move together.4445Schema hosting may use development identifiers such as `1.6.0-dev.8` while the manifest document46uses a release-line identifier such as `1.6.0`. Follow explicit release direction when choosing a47new publication identifier; do not invent a version bump merely to retain the old schema.4849## Workflow50511. Read `cli/golem-cli/src/versions.rs` and identify the schema directory named by52 `manifest_schema_version!()`.532. Modify that current schema in place, or create a new publication directory only when the task's54 release/schema-hosting requirements call for one.553. Update the Rust manifest model and serde behavior so the implementation and JSON Schema describe56 the same contract.574. Update `cli/golem-cli/src/versions.rs`:58 - change `sdk::MANIFEST` only when the YAML document version changes;59 - change `manifest_schema_version!()` only when using a new schema publication identifier.605. If `sdk::MANIFEST` changes, replace the old-version policy in61 `cli/golem-cli/src/app/manifest_version.rs` with the new current contract. Do not keep previous62 versions accepted or generate compatibility upgrades.636. Check every schema-version consumer, especially:64 - `cli/golem-cli/src/lib.rs`65 - `cli/golem-cli/src/app/template/snippet.rs`66 - `cli/golem-cli/src/app/build/check/mod.rs`67 - tests containing embedded `$schema` references687. Update all in-tree manifests, templates, examples, fixtures, tests, and generated artifacts that69 use the changed field or version.708. Run focused validation, checks, and tests.7172## Things To Watch7374- Do not assume `sdk::MANIFEST` and `manifest_schema_version!()` should always match.75- When introducing a new field or enum value, ensure both serde parsing and JSON76 schema validation agree.77- If the CLI emits manifest templates/snippets, make sure they reference the new78 schema version.79- Historical schema directories are publication artifacts, not contracts that current CLI code80 must continue accepting. Leave unrelated history untouched, but do not update it or route current81 behavior through it.8283## Useful Files8485- `cli/golem-cli/src/versions.rs`86- `cli/golem-cli/src/lib.rs`87- `cli/golem-cli/src/app/template/snippet.rs`88- `cli/golem-cli/src/app/manifest_version.rs`89- `cli/golem-cli/src/app/build/check/mod.rs`90- `cli/golem-cli/src/model/app_raw.rs`91- `cli/schema.golem.cloud/app/golem/*/golem.schema.json`9293## Verification Checklist94951. The current schema validates the changed manifest shape and rejects removed shapes.962. Serde parsing and JSON Schema validation agree.973. CLI version constants and emitted `$schema` references point to the sole current contract.984. No compatibility parser, alias, old-version support, upgrade path, migration, or backfill was99 added or retained for the changed contract.1005. All in-tree manifests and generated examples use the current shape.1016. `cargo check -p golem-cli` passes.1027. Focused manifest schema/version tests pass with `--report-time`.