Reference / blueprint
A composition of one or more components into a single deployable application.
JSON Schema · Specification · Examples · Source
This reference is generated from the schema bundle and is informative. Where it differs from the specification, the specification governs. A documented default is an annotation: no validator inserts it.
Structural and type validation only: cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
A composition of one or more components into a single deployable application.
Structural and type validation only: cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
Document kind discriminator. Must be BLUEPRINT.
Version of the Musher specification this document is written against.
Where one receiving input’s value comes from.
Exactly one of parameter, node with output, or value is present. The key present selects the form.
node requires output.
output requires node.
Node whose output supplies the value.
Output of that node.
Installation parameter supplying the value.
Logical non-secret literal value.
The compute a workload node runs on: a compute profile, and optional placement pins that narrow where it is placed. Required on a node whose component runs, forbidden on one whose component is EXTERNAL. See spec.md §4.3.
Optional pins narrowing the eligible hosts. Absent and a block with no pin set mean the same thing.
Compute profile slug in family.tier.size form, for example general.standard.small. The profiles actually on offer are published at https://api.musher.dev/v1/reference/compute-profiles.
Lookahead-free, so it compiles under RE2 as well as ECMA-262. Only the grammar is here; membership is a capability check (spec.md §4.3).
Exposure of one endpoint in the object form: its visibility, whether the platform authenticates viewers, how the workload learns who they are, which of their claims it receives, and which requests pass without a viewer. Bare PUBLIC or PRIVATE is the object form with only visibility.
spec.md §4.5 / ADR 0034 §1-§2 / ADR 0035 §2, §4. A bare PUBLIC or PRIVATE, or the object form. Bare PUBLIC is { visibility: PUBLIC } with every default: access OPEN, viewerIdentity NONE. Every member but visibility applies only to PUBLIC; an identity mode and accessExemptions require AUTHENTICATED; viewerClaims requires an identity mode (BP-NODE-006).
When visibility is PRIVATE, access must not be present.
When visibility is PRIVATE, accessExemptions must not be present.
When visibility is PRIVATE, viewerClaims must not be present.
When visibility is PRIVATE, viewerIdentity must not be present.
Otherwise, accessExemptions must not be present.
Otherwise, viewerIdentity must be "NONE".
spec.md §4.5 BP-NODE-006. A released claim travels in an identity mode, so viewerClaims requires a viewerIdentity other than NONE.
Under the condition above, viewerClaims must not be present.
Whether the platform authenticates and authorizes a viewer before forwarding: OPEN forwards every request, and AUTHENTICATED admits only viewers the installation's access policy authorizes. PUBLIC only; AUTHENTICATED requires an HTTP, HTTPS or WS endpoint.
Requests an AUTHENTICATED endpoint forwards without a viewer, each one the component declares: PATHS, a request under one of its accessExemptions paths, and BEARER, a request with no viewer session that carries a bearer token.
Facts about the viewer released to the workload beside the subject: EMAIL, the viewer's verified email address, and NAME, their display name. Requires a viewerIdentity other than NONE.
How the workload learns who the viewer is: NONE; HEADER, a plain request header; ASSERTION, a signed JWT in a request header; or OIDC, the workload signs viewers in as an OpenID Connect client of the platform. Every value but NONE requires access AUTHENTICATED.
Whether the endpoint can be reached from outside the installation.
Identity and description of a blueprint document. The blueprint carries the item’s revision; its sibling listing carries none. See spec.md §3.
What this application is, in one or two plain-text sentences. Required to publish.
spec.md §3 BP-ID-004. Plain text, never rendered as Markdown, bounded like a listing summary. It describes the deployable application to the people who install and operate it; the sibling listing’s summary remains the storefront copy. Structurally optional so a blueprint can be stored while it is being written; BP-ID-005 requires it of a published one.
Item revision: the position of this release in the catalog item's lineage. Orders releases and nothing more.
Item slug, which must equal the item's directory name.
When componentRef matches ^\.{1,2}/, revision must not be present.
Otherwise, revision is required.
Explicit supplier for each receiving input, keyed by the component’s input name.
Reference to the component document this node deploys, in one of two forms. A repo-local reference begins ./ or ../ and ends .yaml or .yml, and resolves relative to the directory holding this blueprint document; its version is the referenced document's metadata.revision. A published reference is the component's UUID, which names the component across all its revisions, and requires revision to select the one deployed. The relative-path prefix is what tells the two apart: a bare slug is not distinguishable from a UUID.
Both patterns are lookahead-free so they compile under RE2 as well as ECMA-262. A path segment must begin with a letter or digit, which is how . and .. are excluded as interior segments without a negative lookahead; that leaves one spelling per target and keeps the containment check in the semantic phase from having to normalise first.
Compute profile and placement for a node whose component runs. Omitted, and forbidden, where the component is EXTERNAL; that agreement is a semantic check against the component (spec.md §4.3).
Exposure of each of the component’s endpoints, keyed by endpoint name; an endpoint left out is PRIVATE. A WORKER endpoint is never PUBLIC.
Lineage version pinned by a published reference. Required on a published reference and rejected on a repo-local one, where the referenced document's own metadata.revision supplies it.
Storage allocated to each of the component’s volumes, keyed by the component’s volume name.
Named installation value, bound explicitly by the nodes that consume it.
spec.md §5 / ADR 0031 §4 / ADR 0035 §5, §6. A parameter is supplied in one way: submitted (with an optional default), generated, hashed from a generated parameter, or read from outside the documents through from. At most one of default, generator, from and hash, and a hash is never offered in a form.
When generator is present, default must not be present.
When generator is present, from must not be present.
When from is present, default must not be present.
When hash is present, default must not be present.
When hash is present, from must not be present.
When hash is present, generator must not be present.
When hash is present, ui must not be present.
Logical default, replaced by a submitted value. No interpolation.
One whole reference to a value outside the documents: ${{ variables.
Persisted credential generation; a submitted value is rejected.
A hash of a generated parameter, computed once and kept beside it; a submitted value is rejected.
Optional install-form presentation.
Number of random bytes generated for the value.
Encoding applied to securely generated random bytes.
Password hash of a generated parameter.
BCRYPT ($2b$, cost 12) or ARGON2ID (PHC string, m=19456, t=2, p=1).
The generated parameter hashed.
Presentation metadata for an install-form parameter.
spec.md §5.4. The control is derived from the logical schema of the inputs the parameter is bound to rather than declared, so this carries only what a derivation cannot supply.
Human-readable label for each enum member, keyed by the member it names. A member left unlabelled is offered as it is spelled.
Example values illustrating the form a value takes. Never submitted; parameter.default supplies an omitted submission.
Human-readable label shown on the install form.
Relative position of the field within the form. Lower sorts first; a parameter declaring no order sorts after every parameter that declares one.
Standing of the field in the form: PRIMARY is offered directly, SECONDARY behind a disclosure the deploying user opens.
Optional pins that narrow the hosts eligible for the node’s compute profile. A pin never changes the compute the profile names. See spec.md §4.4.
Every term pin is a lowercase token rather than a member of a closed set: the grammar is fixed by this contract, the vocabularies are versioned catalog context, not part of this contract (spec.md §4.4). cpuDedication is the exception: two values are the whole concept.
Required accelerator interconnect, such as nvlink or pcie. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Required accelerator runtimes, such as cuda. An empty array pins nothing, and a term may not repeat. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Exact accelerator SKU class to pin. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Permitted CPU architectures, such as x86_64 or arm64. An empty array pins nothing, and a term may not repeat. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Whether the node's vCPU must be dedicated rather than shared. Omit to pin nothing. This is the one pin whose vocabulary this contract closes; see spec.md §4.4.
Minimum accelerator VRAM in GiB. Omit to pin no floor.
Required network class. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.4.
Opaque identity and immutable version of the private installation snapshot; never a secret-derived hash.
Identity and version of each organization variable the installation read.
When source is EXTERNAL, compute must not be present.
When source is EXTERNAL, gitCommit must not be present.
When source is EXTERNAL, imageDigest must not be present.
When source is EXTERNAL, exposure is required.
When source is EXTERNAL, volumes is required.
Otherwise, compute is required.
Otherwise, imageDigest is required.
When source is GIT, gitCommit is required.
Otherwise, gitCommit must not be present.
Composition, explicit input suppliers, allocation and installation parameters.
Named component instances. At least one is required to publish.
spec.md §4 BP-GRAPH-001. Structurally it may be empty so a blueprint can be stored before its first node is chosen, or after its last one is removed; BP-GRAPH-001 requires at least one node of a published blueprint.
Every value the installation takes from outside the documents: submitted, generated, organization variables and connections. Nothing binds by name.
An opaque identity and an immutable version.
Minimum provisioned IOPS for this volume. Omit to pin no floor.
Allocated size, at or above the component’s minSizeGiB.
Required storage class for this volume, such as local-nvme. Omit to pin nothing. The permitted terms are not a vocabulary this contract defines; see spec.md §4.3.