VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
Appendix: machine-readable definitions#
The definitions ship as one MIT-licensed bundle, vtx-v1-definitions. Where the bundle and this text disagree, this text wins and the bundle is a bug.
| File | Defines |
|---|---|
vtx-ops-1.schema.json |
One line of the text form: every scene op, with open expanded per node type for region, grid and the core catalog, and prefixed extension types. JSON Schema 2020-12 with only local references and closed objects, so constrained-decoding engines can enforce it on agents |
vtx-intent-1.schema.json |
One intent, client to application |
vtx-app-1.schema.json |
Any line an application writes: a scene op or a control line (Section 17) |
vtx-app-events-1.schema.json |
Any line the server writes to an application (Section 17) |
vtx-wire-1.cddl |
The CBOR payload of every frame type of the core, one rule per frame, prefixed by channel (ctl-, scn-, in-, res-, zone-, clip-, any-) |
ext/ |
The eighteen extensions, each in its own folder with its CDDL, schemas and examples; the beta file with the drafts capability; the combined CDDL and schemas with the core and every extension; and registry.json, every identifier the extensions assign, with each extension's profile and status |
examples/valid/ |
A fleet dashboard, a deploy form, a VT grid, templates, agent features (Markdown, extension types, focus, attention, styles), intents, and both directions of an application session |
examples/invalid/ |
Lines that must be rejected: schema violations, scene-rule violations, malformed intents, and bad application lines in both directions |
examples/resources/ |
Two glyph resources (a 1-bit bitmap and a vector path) that the examples refer to by their real SHA-256 |
examples/vectors.json |
Known-answer test vectors (Section 19) |
tools/gen_schemas.py |
The single source of all four JSON Schemas |
tools/make_resources.py, tools/make_vectors.py |
Build the glyph resources and the test vectors |
tools/validate.py |
Runs every check below |
Extension points. The CDDL marks where extensions may add map members or values as standard CDDL sockets (RFC 8610, Section 3.9), each named …-ext: $$limit-ext, $$in-pointer-ext, $$in-gesture-ext, $$in-intent-ext, $$in-a11y-ext, $a11y-action-ext, $res-kind-ext, $permission-ext; for sign-in $auth-method-ext, $$auth-offer-ext, $$auth-ext and $auth-failed-ext; and $$hello-ext, $$ready-ext and $$approval-ext. The core defines none of them. The eighteen extensions live under ext/ in the bundle, beside ext/vtx-1-all.cddl and three combined schemas that hold the core and all of them at once; Section 19 lists them.
What the checks prove. tools/validate.py passes 2,543 checks with no failures: 444 for the core, listed below; 1,819 for the eighteen extensions (94 for Surfaces 1, 44 for Themes 1, 71 for Composites 1, 249 for Media 1, 240 for Transfer 1, 93 for Exec 1, 191 for Devices 1, 141 for Viewers 1, 114 for Sensors 1, 73 for Windows 1, 82 for Displays 1, 55 for Brokering 1, 47 for Drives 1, 52 for Printers 1, 46 for Media Devices 1, 61 for Smart Cards 1, 57 for USB 1, 109 for WASM 1); 141 for the extensions together, their combined files and their registry; 67 for the Wayland Host 1 binding; and 72 for the RDP Bridge 1 binding. The core's checks prove that:
- every valid example line passes its schema, and every valid op stream, including the ops in an application session, also obeys the scene rules of Section 7;
- every invalid line is rejected, for the intended reason;
- the CDDL accepts a sample of every frame payload, the UPDATE frames built from the example streams and every example intent, and rejects 38 malformed samples, among them out-of-range gamepad axes, unknown gestures, incomplete device descriptors, a READY without
input_seqand anx509signature without certificates; - each glyph resource matches its hash and its declared size;
- QUIC varints round-trip, the CREDIT frame encodes to exactly the bytes in Section 3, and every test vector in
examples/vectors.jsonrecomputes from its inputs.
Review. A first independent review compared this text with the definitions and raised 25 issues, among them OIDC token relay, a flow-control deadlock, updates too large for one frame, and a Unicode version the client could not learn. A gap review then found 25 more (below). All 50 are resolved in draft d01 and in the bundle.