Two things the live captures showed that the schemas did not say.
`msg` was missing from the v1 push_status schema, which is the one version
where it is load-bearing. v1 pushes only the fields that changed, except for
a pushall-triggered push which is the whole object, and `msg` is how a v1
message self-describes which it is (0 forced/full, 1 automatic/partial). A
consumer that replaces its cached object with a partial push silently unsets
every field that push did not mention, and there is no other way to tell:
push_status does not echo `sequence_id`, so there is no correlation back to
the pushall that asked for it. continuum-proxy has read this field since the
cache was written; the schema just never declared it.
v2 had it with no description. It is informational there - v2 sends the whole
object every time - so it now points at the v1 note rather than repeating it.
The other half is an absence, which a schema cannot express by staying
silent: v2 has no `vt_tray` because a real v2 printer omits the key entirely
rather than sending an empty object. That is recorded as a comment so nobody
adds it for symmetry with v1, because the distinction is the thing: absence
means "not reported", not "no external spool", and it is exactly why
`EXTERNAL_SPOOLS` in continuum-proxy is a constant instead of being counted
from a report.
Confirmed live: both BambuMQTT versions reply to a calibration request
with a dedicated print.calibration report, not just push_status - the
v1 request schema's own description said the opposite ("printer responds
with push_status instead of calibration"), and v2's report schema framed
this as a v1-vs-v2 contrast that no longer holds. Both descriptions
corrected; the printer does still send ordinary push_status updates
alongside the dedicated report as calibration progresses, same as any
other print job, not instead of it.
Added v1/report/print/calibration.schema.json (only existed for v2
before) and wired it into v1/report.schema.json's print category
dispatcher, which never listed it since the file didn't exist.
- print.schema.json, _ams.schema.json, _ams_unit.schema.json still
pointed at the pre-rename filenames (ams.schema.json, ams_unit.schema.json,
ams_tray.schema.json) after the underscore-prefix split - fixed all
three, verified with a full jsonschema + referencing validation run
against real captures (get_version, pushall, a full print/ams/xcam
report with both empty and loaded trays) plus negative tests.
- _upgrade_state.schema.json: fixed its $id (pointed at report/info/,
file lives under report/print/) and its title (said "ModuleInfo",
clearly copy-pasted from _module_info.schema.json). Wired it into
print.schema.json as the print report's `upgrade_state` property -
the file existed but nothing referenced it yet.
- Deleted schemas/bambulab/v2/, which had been recreated as stale,
broken copies of an older v1 (missing the envelope allOf, missing
the underscore renames, $ids still pointing at v1/ paths) - the
repo's own README documents v2 as intentionally removed until V2's
wire format is known to differ from V1's.
- Updated schemas/bambulab/README.md's layout tree and inheritance-
example reference, both stale after the underscore rename.
- Removed stray tsc -b build output (packages/ts-types/src/*.d.ts/js)
that isn't meant to be committed (outDir is dist/, gitignored).
Verified: cargo check clean (continuum-proxy, continuum-ai-worker,
rust-types), tsc clean (continuum-backend, continuum-common ts-core),
10/10 JSON Schema validation cases passing.
Each root JSON key ('info', 'pushing', 'print') now gets its own category
folder under request/ and report/, so a category can hold multiple command
schemas without flattening them into one directory - v1/request.schema.json
and v1/report.schema.json route into these via oneOf per category (also
future-proofs for a category ever needing more than one shape).
Split pushall's ams/xcam fields the same way module_info was already
split: ams.schema.json/ams_unit.schema.json/ams_tray.schema.json/
xcam.schema.json/print.schema.json, each referencing the next by relative
$ref. ams_tray.schema.json uses oneOf for the empty-vs-loaded tray shapes
- verified (and initially got wrong, then fixed) that LoadedTray needs
every field required, not just id, or a bare {"id":"0"} validates
against both branches and oneOf fails, since oneOf demands exactly one
match.
Real correction: the report/ category for what a pushall request
triggers is "print", not "pushing" - re-reading the original examples,
pushall's REQUEST goes to "pushing", but the resulting state-push stream
arrives under "print", a different root key. report/pushing/ (my
original mistake) is removed; report/print/ holds the corrected content.
request/pushing/ is untouched - that side was correct.
Also: v2/ removed (found as broken copy-pasted stubs still pointing at
v1 $ids - no real V2-specific content yet, better to have nothing than
broken duplicates); all $ids switched to real, verified Gitea raw-file
URLs (raw/branch/main/<path> - confirmed this is the correct pattern,
not raw/<path>) instead of a placeholder domain; fixed a broken relative
$ref in the request-side files left over from an earlier move (still
pointing 2 levels up instead of 3 after nesting one level deeper).
Re-validated everything against real examples after restructuring,
including the full ams/xcam print report and two negative cases -
see schemas/bambulab/README.md for the validation script.
Schemas (any notation - proto, JSON Schema) belong in the schemas repo
regardless of how many languages currently consume them; that's what
makes this 'the schemas repo'. Rust-only code (the hand-written structs
in continuum-proxy's bambu_commands/) is a different category and stays
where it was.
Also restructured per readability feedback:
- envelope.schema.json moved out of v1/ to the bambulab/ root - it's
shared across protocol generations, not v1-specific, same principle
already applied to the (now-removed) proto/bambulab/common.proto.
- v1/ split into v1/request/ and v1/report/, one file per command in
each, instead of *.request.schema.json / *.response.schema.json
filename suffixes doing the same job less clearly. The two top-level
dispatcher schemas (matching BambuRequest/BambuReport) stay at the v1/
root since they aren't themselves a single command's schema.
Re-verified after restructuring, not just moved and assumed still
correct: resolution now has to handle a real basename collision
(get_version.schema.json exists in both request/ and report/) — switched
the validation approach to register schemas by (their actual base
URI) rather than by filename, which is what makes relative resolve
correctly here. All three real examples plus the negative tests from the
original version still pass.
octoturge