Reference / component
A reusable, versioned definition of one graph node: a workload this platform runs (its source, lifecycle, endpoints, storage and health) or an external node it does not, and the configuration contract either consumes and publishes.
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 reusable, versioned definition of one graph node: a workload this platform runs (its source, lifecycle, endpoints, storage and health) or an external node it does not, and the configuration contract either consumes and publishes.
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 COMPONENT.
Version of the Musher specification this document is written against.
Password; a sensitive input, never a literal.
User name, literal or from an input.
Token; a sensitive input, never a literal.
spec.md §5.1. Exactly one of dockerfile and buildpacks says how the source is built; arguments apply to either.
Exactly one of dockerfile or buildpacks is present. The key present selects the form.
Build arguments keyed by argument name, injected into the image build context (Docker ARG). Build-time configuration only; runtime configuration rides on inputs.
Build with Cloud Native Buildpacks.
Build with a Dockerfile, at this path relative to the repository root.
Buildpacks builder image.
The atomic connection this input stands for: an endpoint, a credential and a model acquired together.
Required protocol features. Omission requires no optional capabilities.
Required client protocol, independent of upstream vendor.
Typed input declarations keyed by input name.
Typed output declarations keyed by output name.
spec.md §5.2 COMP-EP-005. Only HTTPS is TLS on the hop to the workload in v1, so only an HTTPS endpoint carries a trust policy.
Under the condition above, tls must not be present.
Protocol the platform speaks to the workload on the port: HTTP, HTTPS, WS, GRPC, TCP, or UDP.
Port the workload listens on, where traffic for this endpoint is forwarded. Never the public port, which the platform allocates. A port below 1024 is structurally valid; admission may reject it as a capability check.
How the platform trusts the workload's certificate. Only on an HTTPS endpoint; omitted, the certificate is verified against publicly trusted roots.
spec.md §5.2 COMP-EP-005 / COMP-EP-007. One policy for every connection the platform makes to the endpoint, routing and probes alike. BUNDLE names its roots and the name to verify; the other modes carry no bundle. serverName is a DNS name, never an IP literal: its last label starts with a letter.
When verify is BUNDLE, serverName is required.
When verify is BUNDLE, trustBundle is required.
Otherwise, trustBundle must not be present.
Name sent in SNI and matched against the certificate. Never changes the address connected to or the HTTP Host header. Omitted, the certificate must be valid for the host the platform connects to. Required with BUNDLE.
Own string input holding the PEM certificates that are the only trusted roots. Required with BUNDLE, and forbidden otherwise.
How the certificate is verified: SYSTEM (publicly trusted roots), BUNDLE (the roots in trustBundle), or NONE (no chain or name verification; an explicit exception for this endpoint).
spec.md §5.1. Exactly one of branch and commit.
Exactly one of branch or commit is present. The key present selects the form.
Branch to build from. A request, not a pin: the branch moves.
Commit to build from. Identifies source, not every build input.
How the repository is built into an image. Required: a Git source has no image until something builds one, and leaving the strategy implicit makes the resulting image depend on the builder rather than on this document.
Branch or commit to build from. Omitted, the repository default branch.
Git repository URL the platform builds into an image.
Staged health probes: startup, readiness, liveness.
Aliveness gate; failure restarts the workload. Optional.
Traffic gate; failure pulls the replica from routing without a restart. Required for a SERVICE exposing a public endpoint.
Initialization gate; failure means not-yet-started. Optional.
An HTTP GET the platform sends over the endpoint's protocol and TLS policy; a 200 to 399 status succeeds unless expectedStatuses says otherwise. Redirects are never followed.
Credentials sent on the probe request only, never on forwarded traffic.
Named endpoint serving HTTP or HTTPS.
HTTP statuses that count as success, replacing the 200 to 399 default for this probe.
spec.md §5.4 COMP-EP-008. A final status is 200 to 599; a 1xx is never the answer to a probe.
Absolute HTTP path the platform requests.
OCI image reference the workload runs from. A bare name means the tag latest, as in Docker. A tag is a request; only an @sha256 digest identifies content.
Lookahead-free so it compiles under RE2 as well as ECMA-262. The tag colon is the one after the final slash, which is what keeps a registry port (localhost:5000/nginx) from reading as a tag. See spec.md §5.1.
Exactly one of schema or connection is present. The key present selects the form.
spec.md §6.4 COMP-CONNECTION-002. A connection input carries none of the value fields: its protocol fixes its members, and it is always required.
Under the condition above, default must not be present.
Under the condition above, presentationHint must not be present.
Under the condition above, required must not be present.
Under the condition above, schema must not be present.
Under the condition above, sensitive must not be present.
Under the condition above, target must not be present.
The connection this input stands for. Only an EXTERNAL component declares one.
Logical fallback used only when no binding is declared.
What this input means.
spec.md §6 COMP-DESC-001 and COMP-DESC-004. A published component describes every input (COMP-DESC-004, capability), and the component is its only home: a blueprint parameter carries no description of its own and shows this one, so a value is described once, by the document that needs it. Absent is a draft still being written; present and empty is never valid.
Optional presentation annotation, not a value constraint.
Whether absence is forbidden; defaults to true.
Logical JSON value contract.
True when the value is secret material: handled as a secret reference, masked in UIs, never echoed back.
Environment destination; required on workload inputs.
spec.md §5.2 COMP-EP-006 / ADR 0033. A value the workload configuration reads enters through one of the component's own inputs.
Own input supplying the value.
Environment variable the resolved value is bound into at runtime materialisation (e.g. ADMIN_EMAIL). Uppercase letters, digits, and underscores; must not start with a digit.
Identity and description of a component document. The name is the file stem.
What this component is, in one or two plain-text sentences. Required to publish.
spec.md §4 COMP-DESC-002. Plain text, never rendered as Markdown, and bounded like a listing summary: it is one or two sentences a composer reads beside a node, not documentation. Structurally optional so a component can be stored while it is being written; COMP-DESC-003 requires it of a published one.
Lineage revision of this component. Required (never defaulted) so the component's content is a pure function of this file, and it is the revision the item's blueprint nodes pin.
What this output means.
Optional presentation annotation.
Logical JSON value contract.
True when the value is secret material: handled as a secret reference, masked in UIs, never echoed back.
Where the output value comes from.
spec.md §6.2 / ADR 0031 §1 / ADR 0033 §2. Where the output value comes from is the key that is present: a literal value, one of this component’s own inputs (with the member read, when the input is a connection input), a property of one of its endpoints, or a template over its own endpoints. Exactly one; endpoint and property are one origin, and each requires the other, and member requires input.
Exactly one of value, input, endpoint with property, or template is present. The key present selects the form.
endpoint requires property.
member requires input.
property requires endpoint.
Own endpoint whose property is read.
Own input forwarded as this output, keeping its sensitivity.
Member of a connection input to forward. Required when the input is a connection input, and forbidden otherwise.
Property of the named endpoint: an allocated address, or the viewer identity header and trusted proxy CIDRs of an endpoint whose blueprint exposure forwards viewer identity.
String with ${{ self.endpoints.
Logical non-secret literal value.
spec.md §5.4. The mechanism is the key that is present, as in a Kubernetes probe. HTTP is the only mechanism in v1; another is added as a sibling key.
Consecutive failures required to consider the probe failing.
Seconds to wait after start before the first probe.
Seconds between consecutive probe attempts.
Consecutive successes required to consider the probe passing.
Seconds to wait for a probe response.
Credentials the probe request carries.
Exactly one of basic or bearer is present. The key present selects the form.
HTTP Basic credentials.
Bearer token credentials.
Where one credential comes from.
Exactly one of value or input is present. The key present selects the form.
Own input supplying the credential.
Literal non-secret value.
Five-field cron expression, evaluated in UTC, on which the JOB recurs.
spec.md §5.7. Five fields (minute, hour, day of month, month, day of week) separated by one or more spaces or tabs, evaluated in UTC. The field count is structural so a seconds field or an @-macro is rejected rather than read two ways. The grammar and range of each field are a semantic rule of spec.md §5.7 (ERR_INVALID_SCHEDULE).
Exactly one of image or git is present. The key present selects the form.
A Git repository the platform builds into an image.
When type is EXTERNAL, contract is constrained by properties.
When type is EXTERNAL, workload must not be present.
Otherwise, contract is constrained by properties.
When type is JOB, workload is constrained by properties.
Otherwise, workload is constrained by properties.
The composition contract: typed inputs the component needs and outputs it publishes.
Category of the node: SERVICE (long-running, request-driven, at least one endpoint), WORKER (long-running, not request-driven; endpoints optional and never public), JOB (runs to completion, once per rollout or on a schedule), or EXTERNAL (not run by this platform).
How the platform runs the component: source, command, endpoints, environment, storage and health. A published SERVICE, WORKER or JOB carries one; forbidden when type is EXTERNAL.
When type is array, items is required.
When type is object, additionalProperties is required.
When type is object, properties is required.
When type is string, additionalProperties must not be present.
When type is string, exclusiveMaximum must not be present.
When type is string, exclusiveMinimum must not be present.
When type is string, items must not be present.
When type is string, maxItems must not be present.
When type is string, maximum must not be present.
When type is string, minItems must not be present.
When type is string, minimum must not be present.
When type is string, properties must not be present.
When type is string, required must not be present.
When type is string, uniqueItems must not be present.
When type is number, additionalProperties must not be present.
When type is number, items must not be present.
When type is number, maxItems must not be present.
When type is number, maxLength must not be present.
When type is number, minItems must not be present.
When type is number, minLength must not be present.
When type is number, pattern must not be present.
When type is number, properties must not be present.
When type is number, required must not be present.
When type is number, uniqueItems must not be present.
When type is integer, additionalProperties must not be present.
When type is integer, items must not be present.
When type is integer, maxItems must not be present.
When type is integer, maxLength must not be present.
When type is integer, minItems must not be present.
When type is integer, minLength must not be present.
When type is integer, pattern must not be present.
When type is integer, properties must not be present.
When type is integer, required must not be present.
When type is integer, uniqueItems must not be present.
When type is boolean, additionalProperties must not be present.
When type is boolean, exclusiveMaximum must not be present.
When type is boolean, exclusiveMinimum must not be present.
When type is boolean, items must not be present.
When type is boolean, maxItems must not be present.
When type is boolean, maxLength must not be present.
When type is boolean, maximum must not be present.
When type is boolean, minItems must not be present.
When type is boolean, minLength must not be present.
When type is boolean, minimum must not be present.
When type is boolean, pattern must not be present.
When type is boolean, properties must not be present.
When type is boolean, required must not be present.
When type is boolean, uniqueItems must not be present.
When type is null, additionalProperties must not be present.
When type is null, exclusiveMaximum must not be present.
When type is null, exclusiveMinimum must not be present.
When type is null, items must not be present.
When type is null, maxItems must not be present.
When type is null, maxLength must not be present.
When type is null, maximum must not be present.
When type is null, minItems must not be present.
When type is null, minLength must not be present.
When type is null, minimum must not be present.
When type is null, pattern must not be present.
When type is null, properties must not be present.
When type is null, required must not be present.
When type is null, uniqueItems must not be present.
When type is array, additionalProperties must not be present.
When type is array, exclusiveMaximum must not be present.
When type is array, exclusiveMinimum must not be present.
When type is array, maxLength must not be present.
When type is array, maximum must not be present.
When type is array, minLength must not be present.
When type is array, minimum must not be present.
When type is array, pattern must not be present.
When type is array, properties must not be present.
When type is array, required must not be present.
When type is object, exclusiveMaximum must not be present.
When type is object, exclusiveMinimum must not be present.
When type is object, items must not be present.
When type is object, maxItems must not be present.
When type is object, maxLength must not be present.
When type is object, maximum must not be present.
When type is object, minItems must not be present.
When type is object, minLength must not be present.
When type is object, minimum must not be present.
When type is object, pattern must not be present.
When type is object, uniqueItems must not be present.
Smallest allocation the component can run with. The blueprint allocates at least this.
Absolute path where the volume is mounted in the workload.
True when the volume is mounted read-only.
Arguments the workload runs, as a list, with no shell. Replaces the image CMD and keeps its ENTRYPOINT. A published JOB carries one.
spec.md §5. Exec form: each item is one argument and no shell parses them. It replaces the image CMD and keeps its ENTRYPOINT, which is what command means in Docker and Compose.
Named ports the workload listens on. A published SERVICE declares at least one; optional on a WORKER (never exposed publicly), forbidden on a JOB.
Staged health probes (startup, readiness, liveness). Omitted when none are defined; forbidden on a JOB.
Makes a JOB recur. Omitted, the job runs once per rollout. Forbidden on every other type.
Where the workload image comes from: an image, or a Git repository the platform builds. A published workload carries one.
Persistent storage the workload mounts, with the minimum size each needs.