Canonical public contracts, normative schemas, and language-neutral conformance suites for the Musher platform.
This repository is the source of truth. If an implementation disagrees with the schemas and conformance fixtures published here, the implementation is defective.
Each family is an independently versioned document contract. All three share the
{ specVersion, kind, metadata, spec } envelope described in
ADR 0001.
| Family | kind | Describes | Schema |
|---|---|---|---|
component | COMPONENT | One reusable workload definition — source, runtime shape, health, and configuration contract. | component.schema.json |
blueprint | BLUEPRINT | A composition of components into a single deployable application. | blueprint.schema.json |
listing | LISTING | The catalog storefront entry for a blueprint or component. | listing.schema.json |
Add a modeline to the top of the document:
# yaml-language-server: $schema=https://schemas.musher.dev/component/v1/component.schema.jsonspecVersion: v1kind: COMPONENTOr bind by glob in VS Code settings.json:
{
"yaml.schemas": {
"https://schemas.musher.dev/component/v1/component.schema.json": [
"**/components/*.yaml",
"**/component-*.yaml"
],
"https://schemas.musher.dev/blueprint/v1/blueprint.schema.json": "**/blueprint.yaml",
"https://schemas.musher.dev/listing/v1/listing.schema.json": "**/listing.yaml"
}
}| URL | Mutability | Use for |
|---|---|---|
https://schemas.musher.dev/component/v1/component.schema.json | Moves within the v1 family | Editors, humans |
https://schemas.musher.dev/component/v1.2.0/component.schema.json | Immutable forever | CI, automation, audit |
Automation MUST pin an exact version. Major-version aliases exist so editors pick up backward-compatible additions without a config change; they are not a stable target for a build.
Every published schema is a self-contained compound document — all $refs
resolve inside $defs. No validator ever needs to make a network request to
evaluate a document. Download the tagged release tarball from
Releases and vendor it.
specifications/<family>/v<major>/
spec.md normative prose
schemas/src/ authored schema modules (normative input)
schemas/dist/ generated compound bundle (normative output, committed)
examples/ validated example documents
conformance/<family>/v<major>/
cases.json test-vector index
<phase>/<case-id>/ metadata.json, case.yaml, diagnostics.json
tools/ non-normative build and validation scripts (Bun + TypeScript)
docs/adr/ architecture decision records
schemas/dist/ is generated. Never edit it by hand — CI regenerates it and
fails the build if your commit does not match.
See CONTRIBUTING.md and GOVERNANCE.md.
task setup # install tooling and git hooks
task check # everything CI runs
task bundle # regenerate schemas/dist/ after editing schemas/src/Directories are compatibility epochs (v1); exact releases are git tags of the
form <family>/v<MAJOR>.<MINOR>.<PATCH> — for example component/v1.2.0.
Families version independently.
- Minor — new optional fields. Validation never becomes stricter within a major version.
- Patch — corrections that do not change what validates.
- Major — anything that makes a previously valid document invalid. Requires
a new
v<N>directory; the old one keeps working.
Released versions are immutable. A flawed release is superseded, never overwritten.
v1 is pre-stable. The schemas here were seeded from the platform's
generated catalog schemas and are being brought up to specification quality.
The $defs names are now settled; the normative prose is not — see the TODO
sections in each spec.md, and the open issues.