JSON Contract

Versioning

Rocky’s CLI output is the interface contract with orchestrators like Dagster. Every JSON output includes a top-level version field that tracks the engine’s release version — it’s set from env!("CARGO_PKG_VERSION") at compile time, so the field reports whichever Rocky binary is producing the output.

Examples throughout the reference docs show "version": "1.6.0" to match the current engine release:

{
  "version": "1.6.0",
  "command": "discover",
  ...
}

Stability Guarantees

Rocky follows the engine’s semver cadence:

• Patch (1.6.x) — Bug fixes, no schema changes.
• Minor (1.x.0) — New optional fields may be added. Existing fields are never removed or renamed within a minor series.
• Major (x.0.0) — Breaking changes to field names, types, or structure. Consumers should pin or branch their parsing logic on the major version.

Consumers should parse defensively — tolerate unknown fields, treat absent optional fields as null, and don’t assume the set of enum variants is closed.

Asset Key Format

The asset_key field in materializations and check results follows a fixed format:

[source_type, ...component_values, table_name]

Example: ["fivetran", "acme", "us_west", "shopify", "orders"]

Multi-valued components (like regions) are joined with __:

["fivetran", "acme", "us_west__us_central", "shopify", "orders"]

This format is consumed by dagster-rocky to build Dagster AssetKey objects.

Parsing

Use the parse_rocky_output() function in dagster-rocky to auto-detect the command type:

from dagster_rocky import parse_rocky_output

result = parse_rocky_output(json_str)
# Returns: DiscoverOutput | RunOutput | PlanOutput | StateOutput | ...

The command is detected from the "command" field in the JSON. Shape-based discrimination (e.g. column vs model lineage) covers the commands whose output shape is disambiguated by the presence of an argument.

Codegen Pipeline

Rocky’s JSON output schemas are autogenerated from typed Rust structs. Every CLI command that emits --output json is backed by a struct in engine/crates/rocky-cli/src/output.rs (or commands/doctor.rs) that derives JsonSchema. The full pipeline:

1. Edit the relevant *Output struct in output.rs.
2. Run just codegen from the monorepo root.
3. That exports 37 JSON schemas to schemas/, regenerates Pydantic v2 models in integrations/dagster/src/dagster_rocky/types_generated/, and TypeScript interfaces in editors/vscode/src/types/generated/.
4. Commit the schema and regenerated bindings together.

The codegen-drift CI workflow fails any PR where committed bindings don’t match just codegen output. The .git-hooks/pre-commit hook mirrors the same check locally — enable once with just install-hooks.

As of the latest release, there are 37 typed output schemas covering every JSON-emitting command. See the JSON Output reference for the per-command payload shapes.

Adding New Fields

When adding fields to Rocky’s JSON output:

1. Add the field as optional (nullable) in the relevant Rust *Output struct.
2. Run just codegen to regenerate Pydantic models and TypeScript interfaces.
3. The new field ships with the next minor engine release; no separate schema version bump is needed.
4. Document the new field in the JSON Output reference.