Reading the file back

Four commands contact nothing and change nothing. Run them before you ever run ob plan.

Command	Answers
ob validate	Does this file satisfy the contract?
ob canonical	What did Onebox understand, and where did each value come from?
ob preview	What Compose runtime will it generate?
ob schema	What does my editor need to help me while I type?

ob canonical is the one to read in review

It prints every effective value with its origin annotated:

• # default (Onebox chose it
• # shorthand) you wrote it at the top level and it became a workload field
• # override: an environment override supplied it

The difference between a value someone chose and one that appeared by itself is exactly what a person checking a production configuration needs to see, and it is invisible in the file you wrote.

ob schema supports editor validation

ob schema --out onebox.schema.json

Or reference the published copy from the first line of the project:

# yaml-language-server: $schema=https://onebox.run/schemas/application/v1alpha2/application.schema.json
apiVersion: onebox.run/v1alpha2

The published schema is available at https://onebox.run/schemas/application/v1alpha2/application.schema.json.

The schema is generated from the same declarations the loader enforces and is checked against the conformance corpus, so what your editor tells you while you type is what ob validate tells you afterwards.

One place your editor is ahead of the engine

The published schema includes backupTargets, services.<name>.backup and externalServices. Your editor will complete them and ob validate accepts them, but the behaviour behind them is not yet executable; see Shipped vs proposed.

Reading the whole command surface

So an agent need not find out by trying, every command’s help states whether it contacts the server and whether it changes anything, and the structured output contracts classify every command that accepts --output, with the modes each one takes.

ob exec is the only command in that table that refuses JSON. It records invocation evidence but makes no claim about the result, and nothing it changes belongs to any release. See its safety boundary.