Skip to content

SPLAT JSON Schema + camelCase docs/examples + CI validation#26

Merged
stackedsax merged 4 commits into
mainfrom
fix/splat-camelcase-docs
Jul 18, 2026
Merged

SPLAT JSON Schema + camelCase docs/examples + CI validation#26
stackedsax merged 4 commits into
mainfrom
fix/splat-camelcase-docs

Conversation

@stackedsax

Copy link
Copy Markdown
Contributor

What

The SPLAT JSON Schema, plus the docs/examples fix it surfaced, as one coherent
change. Supersedes #24 (its schema commit is included here).

  1. Generate the schema from the Go typesinternal/splat/schema reflects
    splat.Job into schema/splat.schema.json (draft 2020-12), with Quantity
    and Duration mapped to strings. Regenerate with make schema; a drift test
    keeps it in sync.
  2. Fix the field casing — BAMMM parses SPLAT via json tags, so it only
    accepts camelCase, but SPEC.md and every examples/*.yaml used
    snake_case and were silently dropping those fields at parse time.
    Rewrote all first-class fields to camelCase (scheduler-specific
    extensions.* keys left as-is), and removed the aspirational
    placement.mpi_mapping from full-reference.yaml.
  3. Gate it in CI — a Go test validates every example against the schema, so
    a stray or mis-cased field now fails go test ./... instead of silently
    losing data.

Why combined

The schema and the casing fix are two halves of one thing: the schema is only
correct/useful once the examples match it, and the CI gate ties them together.
Splitting them created a circular dependency (the gate needs both camelCase
examples and the schema), so they land together.

Testing

  • go test ./internal/splat/schema — schema drift check, shape check, and all 9
    examples validate.
  • Confirmed at runtime: converted examples now emit their fields (e.g.
    slurm-job.yaml--cpus-per-task=4 --mem=8G), which they didn't before.
  • Full suite / vet / gofmt clean.

New deps: github.com/invopop/jsonschema, github.com/santhosh-tekuri/jsonschema/v6.

🤖 Generated with Claude Code

stackedsax and others added 4 commits July 18, 2026 14:28
Add internal/splat/schema, which reflects splat.Job into a JSON Schema
(draft 2020-12) with the opaque scalar wrappers (Quantity, Duration) mapped
to strings. The committed schema/splat.schema.json is regenerated with
`make schema` (go test ./internal/splat/schema -update); a drift test runs
under `go test ./...` so the schema can never silently fall out of sync with
the types.

Depends on github.com/invopop/jsonschema (kept out of the core splat package
via the reflector's type Mapper).

Note: validating the current examples/ against this schema fails because they
use snake_case field names while the types/schema use camelCase — a
pre-existing docs/impl mismatch tracked separately; the schema here reflects
what the tool actually accepts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PnTz6Zxqa4jHocK8kCbyx
BAMMM parses SPLAT via sigs.k8s.io/yaml, which honors the json tags — so the
tool only accepts camelCase field names (cpusPerTask, memoryPerTask, ...). But
SPEC.md's field reference and every examples/*.yaml used snake_case, so those
fields were silently dropped when actually parsed.

Rewrite the first-class SPLAT fields to camelCase across SPEC.md and examples/
(scheduler-specific extensions.* keys are left as-is — they are freeform
passthrough matching what each parser writes). Also drop the aspirational
placement.mpi_mapping block from full-reference.yaml (not a real field).

All examples now validate against schema/splat.schema.json and, more
importantly, actually round-trip through `bammm convert` without dropping
fields.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PnTz6Zxqa4jHocK8kCbyx
Add a Go test (santhosh-tekuri/jsonschema/v6) that compiles
schema/splat.schema.json and validates every examples/*.yaml against it. It
runs under `go test ./...`, so a future example with a stray or mis-cased
field fails CI instead of silently dropping data at parse time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PnTz6Zxqa4jHocK8kCbyx
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PnTz6Zxqa4jHocK8kCbyx
@stackedsax
stackedsax force-pushed the fix/splat-camelcase-docs branch from b1efadb to 22521d4 Compare July 18, 2026 21:28
@stackedsax
stackedsax merged commit 8435b5b into main Jul 18, 2026
8 checks passed
@stackedsax
stackedsax deleted the fix/splat-camelcase-docs branch July 18, 2026 21:33
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