fix(schemas): stop a broken refresh from installing an empty schema

[Denis-hamon]

What this is

The tooling prerequisite for the two v2 lots that follow. It does two things: it stops make schemas from installing a broken file, and it gives the v2 catalogue a refresh target it never had.

The defect, measured

make schemas UNIVERSE=<name> pipes curl into jq. When the download fails without producing an error document, curl's exit code is lost to the pipe, jq turns an empty body into an empty file and exits 0, and the mv installs it over a working schema.

sabotage	before	after
unresolvable host	exit 0, support.json replaced by 0 bytes	exit 6, schema untouched, no leftovers
404 (unknown universe)	exit 5, schema intact, one temporary file left behind	exit 56, no leftovers

An empty schema embeds, builds and passes vet. It surfaces at runtime: a command asks it for an enumeration and answers value of openapi must be a non-empty string to somebody who typed a server name.

The 404 case is caught today, but by accident — jq cannot iterate over the API's error document, so the && chain stops. That is luck, not a check.

The download now goes to a file, where curl's own exit code is the one being tested, and the document has to declare an openapi version and at least one path before it may replace anything. Temporary files are removed on any exit.

schemas-v2

The v2 catalogue could not be reached from here at all: v2 APIs are addressed by path (/dedicated/server, /backupServices), not by universe name. So every v2 schema in this repository is a file placed by hand.

Four of them — iam.json, vrackservices.json, vmwareclouddirectorbackup.json, vmwareclouddirectororganization.json — are v2 documents stored under a name with no _v2 suffix, and make schemas UNIVERSE=iam answers 404. They have no refresh path today.

make schemas-v2 API=dedicated/server NAME=baremetal_v2
installed internal/assets/api-schemas/baremetal_v2.json (7 paths)
  9	Alpha version

It deliberately does not curate. The v2 schemas here are a hand-picked subset of the paths the CLI exposes, and deciding what belongs in one is a judgement call, not a transformation. It does print the maturity breakdown of what it just pulled in, because Internal use only is the one thing a curator has to look at and it is invisible in a 2 MB diff.

A test that reads the schemas

Nothing in the build looked inside these files. The new test reads every one of them the way internal/openapi does. It embeds the whole directory rather than its *.json, so a leftover from a failed refresh reaches the test too.

It found a live defect

telephony.json does not validate. Two POST operations — on .../easyHunting/{serviceName}/hunting/queue/{queueId}/agent and its ovhPabx twin — declare billingAccount and serviceName as path parameters and not queueId. The validator reports the first one it meets, so fixing one alone changes nothing.

The document is unusable as a result, and ovhcloud telephony edit fails at the schema-filtering step for every account:

FilterEditableFields(telephony) -> failed to validate spec: invalid paths: operation POST
  /telephony/{billingAccount}/easyHunting/{serviceName}/hunting/queue/{queueId}/agent
  must define exactly all path parameters (missing: [queueId])
FilterEditableFields(support)   -> operation put /support/tickets/{ticketId} not found

The second line is the positive control: the same code path on a valid schema returns a path-specific error, not a validation one.

That is upstream and not this repository's to fix, so it is named in knownInvalidSchemas with its reason. The test insists it still fails: the day it is fixed, the list goes red and asks to be shortened.

Two observations, not changes

Neither is touched here — both are curation decisions for the maintainers.

• cloud_v2.json carries two paths that the current v2 catalogue no longer has: /publicCloud/project/{projectId}/floatingIp and /floatingIp/{floatingIpId}. The CLI drives floating IPs through v1, so nothing calls them.
• The curation rule recorded in .github/copilot-instructions.md says Internal use only paths are never curated in. cloud_v2.json contains 113 operations badged Internal use only, against 21 alpha, 16 stable and 2 beta. The rule and the file disagree today.

Verification

go build, go vet, make wasm, go test ./..., docgen — all clean.

Five sabotages, five red: an emptied schema, a schema reduced to {}, a leftover file in the directory, telephony removed from the known list, and a valid schema wrongly declared invalid. Restoration checked by digest.

One of them was first aimed wrong — patching a single telephony operation left the twin, so the test stayed green and looked like it had no teeth. Re-aimed at the branch it was meant to exercise, it goes red. The count above is the corrected run.

Stacked on #261.

Second commit: finding the paths this repository ships that no longer exist

The target above refreshes a schema. It cannot tell you that a schema needs
refreshing, and one here badly did.

baremetal.json has one commit in the whole history of this repository — the
initial one, of 11 September 2025. Five of its 126 paths are no longer published by
the catalogue, and every one probed against the live API answers 404, including
under the method it declares:

path	declared	live
/dedicated/server/{serviceName}/install/hardwareRaidSize	GET, Stable production version	404
/dedicated/server/{serviceName}/install/start	POST, Stable production version	404
/dedicated/server/availabilities	GET	404
/dedicated/server/availabilities/raw	GET	404
/dedicated/server/datacenter/availabilities/raw	GET	404

The control that settles it: POST with no Authorization header returns 401
on a route that exists (changeContact) and 404 on these, on eu and on ca
alike. The router does not know them — this is not an account lacking a grant. And
the same request to a path invented on the spot returns the identical body, word for
word.

vrack.json carries three more, telephony.json two; ip.json, me.json and
support.json carry none. The file also badges reinstall Beta while it answers,
and install/start Stable production version while it does not — which is why this
does not look like a production snapshot that merely went stale.

Nothing in the CLI calls those paths today, so this is a contract defect rather than
a breakage. It becomes one the day a command is built on a path that has been gone
for a year, which is exactly what an embedded schema invites.

$ make schemas-drift NAME=baremetal SOURCE=v1/dedicated/server
baremetal.json: 126 paths embedded, 123 published by v1/dedicated/server
  embedded but not published — these will 404:
    /dedicated/server/availabilities
    ...

$ make schemas-drift NAME=support SOURCE=v1/support
support.json: 9 paths embedded, 9 published by v1/support
  no embedded path is missing from the catalogue

The target refuses to conclude from an unusable answer rather than reporting every
path as dead — checked against a catalogue path that does not exist, it exits
non-zero instead of printing 126 false positives.