Modelines point at API payload schemas, not the published document schemas

[justinmerrell]

Summary

Every document in this repo binds its editor schema to the platform's API endpoint:

# yaml-language-server: $schema=https://api.musher.dev/v1/schemas/component-create
specVersion: v1
kind: COMPONENT
metadata:
  slug: hello-http
spec:
  workload: …
  contract: …

That endpoint serves the request-body schema for POST /v1/…/components, which declares
only metadata and spec. It has no specVersion and no kind. The two keys every file here
writes are not in the schema it points at.

They have worked so far only because the platform's request models inherited Pydantic's default
extra="ignore", so the API silently discarded both.

What is changing

Two things landed that turn this from cosmetic into breaking:

1. musher-dev/spec is now the normative source for the three document families
   (component, blueprint, listing) and publishes their schemas statically. Those schemas
   do declare the {specVersion, kind, metadata, spec} envelope these files actually use.
2. musher-dev/platform now rejects unknown properties on every request body
   (additionalProperties: false), per spec specifications/component/v1/spec.md §2 and
   platform ADR 0123. Once that ships, specVersion and kind stop being ignored and start
   returning 422.

The platform's /v1/schemas collection has been re-documented to say plainly that it publishes
API payload schemas and is not the authoring-document channel.

The fix

Repoint each modeline at the published document schema:

File	Current	Should be
*/musher/component*.yaml	https://api.musher.dev/v1/schemas/component-create	https://schemas.musher.dev/component/v1/component.schema.json
*/musher/blueprint.yaml	https://api.musher.dev/v1/schemas/blueprint-compose	https://schemas.musher.dev/blueprint/v1/blueprint.schema.json

Affected: configurable-greeter, counter-with-cache, hello-http, notes-with-volume,
queue-worker — every musher/*.yaml in the repo.

Note schemas.musher.dev is not serving yet (musher-dev/spec ADR 0001 follow-up #1, owned by
musher-dev/infra), so this wants to land after that DNS record exists — otherwise the modeline
points at a dead host and editor validation silently stops working. Until then the documents are
correct as authored; it is only the $schema pointer that is wrong.

A second, deeper mismatch worth knowing about

blueprint.yaml here addresses nodes by componentId + componentVersion, substituted by
scripts/musher-apply.sh from ids that do not exist until the components have been created. A
blueprint that cannot reference a component until that component exists is not a document a user
can write by hand — which is why these examples need a shell script to deploy.

musher-dev/spec issue #8 proposes collapsing that to a single form-discriminated component
field, where a repo-local reference is a relative path:

components:
  web:
    component: ./component.yaml
    size: general.standard.small
    connections: {}

That would let these examples drop the id-substitution step entirely. It also fixes a second
problem: the currently published blueprint schema resolves a node reference as
components/<stem>.yaml, so this repo's flat musher/ layout is not expressible in it at all.

No action needed here yet — flagging it so the modeline fix and that change can be sequenced
together rather than editing these files twice.

Related

• musher-dev/spec ADR 0001 §5 — why the API endpoint is not the authoring channel
• musher-dev/spec issue #8 — the node-reference proposal
• musher-dev/platform ADR 0123 — request-body strictness