Skip to content

CONCEPT Cited by 1 source

JSON output stability

JSON output stability is the commitment that a CLI's structured output (JSON via --output json, YAML via --output yaml, or equivalent) uses field names that stay stable across tool versions, so an agent that parsed last month's output still parses this month's output. It is the load-bearing agent-ergonomic invariant that turns an LLM's parsing glue into a cached, reusable capability instead of an every-session rediscovery exercise.

Why stability matters more for agents than humans

A human parsing CLI JSON accommodates renames trivially: "Oh, alerts became alert_rules, fine, update the jq filter." An agent session that planned around last week's field names silently breaks — the tool exits 0, the JSON parses, and the agent's next step operates on the wrong fields.

The verbatim commitment from the gcx launch post:

"Every command emits JSON or YAML via --output, with field names that stay stable across versions. That way, an agent parsing today's response will still work next month."

The "stays stable across versions" clause is what elevates --output json from a developer ergonomic into a first-class agent contract.

What stability actually means

Stability isn't schema immutability. It's a discipline with concrete enforceable clauses:

  1. No silent renames. Once a field name is shipped, it isn't renamed. If the concept changes, a new field is added; the old one stays.
  2. Additive evolution only. New fields may be added; existing fields may not be removed within a major version.
  3. Type stability. A field that was a string stays a string. Boolean-to-enum migrations happen via new field names + a deprecation window (see patterns/backward-compatible-config-migration).
  4. Deprecation windows. If a field must be removed, a named deprecation path makes that explicit — usually flagged in the machine-readable catalog (concepts/machine-readable-command-catalog).

Failure modes without stability

  • Session-level parser rot. Agent writes a jq / jsonpath / Pydantic model against the tool's output; six weeks later a minor version renames alerts to alert_rules; next run silently drops all alerts from the agent's plan.
  • Retry-loop pathology. Agent sees an empty array after a rename, "retries with different arguments", burns tokens on a phantom problem.
  • Training-data drift. The training data the LLM learned the tool's shape from is a specific version's output; stability means that prior-version knowledge still lands.

Relationship to adjacent concepts

How vendors enforce it (open question)

The gcx launch post asserts the commitment but doesn't disclose enforcement. Likely mechanisms (from adjacent wiki sources):

  • Contract tests that snapshot the output schema and fail CI on uncoordinated changes.
  • A schema-registry or OpenAPI-like document that is the authoritative field list.
  • Deprecation-window tooling that auto-flags removals in review.
  • The machine-readable catalog itself being part of the release artifact, so agents can diff catalog versions on upgrade.

Future posts may mechanise this. The commitment on its own is the architecturally-interesting datum.

Seen in

Last updated · 433 distilled / 1,256 read