Skip to content
Trazum

Building on the JSON

Documentation / JSON output · Format contracts · Local HTTP API

For people writing a dashboard, a CI step or an importer against what Trazum prints with --json.

This page is a map. It says where each command's contract is, what a contract promises and what it does not, and what never leaves the machine. The contract itself is JSON output: every field is described there, and nothing on this page restates one.

Each command's contract#

Each link goes to the section of JSON output that holds the field table for that command's document.

CommandContract
trazum profile --jsonTop-level fields
trazum profile --by-source --jsonThe --by-source document
trazum plan --jsonThe plan document
trazum verify --jsonThe verification document
trazum history --jsonThe history document
trazum connect --jsonThe connected report document
trazum serve, POST /costThe cost answer document
spend_guard over MCPThe spend-guard document
trazum init --jsonThe first-run document
trazum report --year <yyyy> --jsonThe annual record document
trazum rollup <document...> --jsonThe roll-up document
trazum pulse --jsonThe pulse document
trazum proactive --jsonThe proactive document
trazum waste --jsonThe waste document
trazum bench --jsonThe bench document
trazum rules --measure <dir> --jsonThe rule-yield document
trazum write --jsonThe prompt-draft document
trazum gateway, HTTP 402The gateway refusal document
trazum position <usage.jsonl> --jsonThe position document
trazum route ... --json --yesThe routing-measurement document
trazum prune ... --json --yesThe example-pruning document
trazum store --jsonThe store inventory document
trazum conform <file> --jsonThe conformance document
trazum watch --jsonThe watch cycle document
Task reports, comparisons and policy receipts (2.6.0 and later)The task document

The outcome report document has no command that prints it: it is documented for a tool that computes it with @trazum/core.

The contracts are versioned and held by tests#

  • Versioned. A document that follows the schemaVersion promise carries schemaVersion, which starts at 1. The task family uses version and kind instead, and you branch on those. Which of the two a document uses is stated in its section.
  • Held by tests, in both directions. A key that disappears fails a test, and a key added without a line in JSON output fails one too. contract-coverage.test.js takes every table out of that file and fails on one that no test claims, and on a claim for a table that no longer exists.
  • The promises are tested as well as the tables. format-promises.test.js runs the promises of the next section over the documents the core can build.
  • You can validate without Trazum. trazum schema <name> prints a contract as JSON Schema, and it lists the fields a reader may rely on, which is fewer than a document carries. The task family is the exception: schema and conform do not support it. See the contracts as JSON Schema and trazum conform.

What is stable and what is not#

Stable, from the promise:

  • schemaVersion is the only thing to branch on. It changes only when a field's meaning changes or a field is removed.
  • Fields are added without a version bump. Ignore keys you do not know and your reader keeps working.
  • Dollars are numbers, never strings and never rounded for display. Token counts are integers.
  • No document carries a session key or prompt text.
  • Absence is null or an empty array, never zero. null means not measured.

Not stable, and not a promise:

  • Which keys exist beyond the ones a table names. New keys arrive without notice, which is why an unknown key must not break you.
  • The wording of any sentence. An advisory's detail is for a person: read it for display and never parse it. The id, the severity and estimatedMonthlyUsd are the fields (the capability an advisory names).
  • The bundled prices. A figure depends on the catalogue the version you ran carried. A price can change in a patch release, so the same log can price differently on two versions, and a --pricing overlay corrects one today (Changing prices).
  • A roll-up is not a measurement made here. It merges documents other machines measured, and what matters in it is its refusals. Read them before you quote a total.

Nothing is uploaded#

Reading these documents sends nothing anywhere. Trazum does not collect them, there is no account, and no hosted service receives usage, so there is no leaderboard and nothing to rank. A roll-up is a format and a merge, not a service: the documents travel however your team already moves files. What you build on the JSON stays where you put it.

Where to go next#