Skip to content

feat: add hand-authored manifest JSON schema for editor validation#168

Merged
joshua-temple merged 1 commit into
mainfrom
feat/manifest-json-schema
Jun 15, 2026
Merged

feat: add hand-authored manifest JSON schema for editor validation#168
joshua-temple merged 1 commit into
mainfrom
feat/manifest-json-schema

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

Problem

Authoring .github/manifest.yaml has no editor support: no autocomplete, no type checking, no enum hints, no hover docs. Typos and wrong-typed fields are only caught at parse-config time.

Approach

Add a hand-authored draft-07 JSON Schema for the manifest. It is hand-authored (not generated) so the union fields can be modeled precisely:

  • secrets: oneOf the scalar "inherit", {inherit: bool}, or an explicit secret-name map (the map form disallows an inherit key to keep the union unambiguous).
  • runs_on: oneOf a single label, a list of labels, or a {group, labels} object requiring at least one of the two.
  • concurrency: a closed {group, cancel_in_progress} object.

The schema is embedded and printed by a new cascade schema command (--output to write a file). The JSON Schema validator used to test it is a test-only dependency and never enters the binary.

A drift test is the lockstep guarantee against schema/type drift: it validates a corpus of real manifests (cascade's own manifest, every e2e/scenarios/*.yaml config block, and the README ci: examples) and asserts known-bad documents are rejected (unknown top-level key, environments as a string, secrets as an integer, a build missing name). A sibling test asserts the three on-disk copies of the schema stay byte-identical.

The schema is published at https://stablekernel.github.io/cascade/manifest.schema.json. Editors register it via the # yaml-language-server: $schema=... directive or a yaml.schemas mapping; both are documented under Configuration -> Editor support, with a cascade schema entry in the CLI reference and a pointer from the adoption guide. parse-config remains the authority for semantic and cross-field rules.

Verification

  • go build ./... && go test ./... && golangci-lint run ./... all clean.
  • Drift-test corpus passes; known-bad cases are rejected.
  • Validator confirmed test-only: absent from the built binary; go mod why resolves only to the test package.
  • cascade schema and cascade schema -o <file> print/write the schema, matching the committed copy.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple merged commit 50243ed into main Jun 15, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant