FFX Machine-Readable JSON Schemas Specification

This document blueprints the architectural framework and type safety constraints governing machine-readable JSON outputs inside fuchsia.git.

Architectural Overview

To support automation scripts, continuous integration hooks, and high-level developer orchestration tools, many ffx subcommand plugins emit structured, machine-parseable outputs when invoked with the global flag:

ffx --machine json <subcommand>

To ensure these data blocks maintain strict backward compatibility contracts and do not induce silent breakdown regressions downstream, all machine-parseable types are strongly typed and validated via compile-time schemas.

The Schemars Integration Framework

Fuchsia utilizes the schemars Rust crate to enforce programmatic schema generation. Plugin authors define an output payload enum or structure type representing the console data payload and derive the traits:

use schemars::JsonSchema;
use serde::Serialize;

#[derive(Debug, Serialize, JsonSchema, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum CommandOutputMessage {
    Message(String),
    Data(serde_json::Value),
}

Deriving JsonSchema enables the compilation toolchain to automatically reflect and extract the corresponding schema layout mapping matrix.

Output Transmission via VerifiedMachineWriter

Plugins that support machine-readable output use a specialized writer class VerifiedMachineWriter provided by the ffx_writer framework library:

impl FfxMain for MyTool {
    type Writer = VerifiedMachineWriter<CommandOutputMessage>;

    async fn main(self, mut writer: Self::Writer) -> fho::Result<()> {
        // ...
        writer.item(&CommandOutputMessage::Message("Operation successful.".into()))?;
        Ok(())
    }
}

VerifiedMachineWriter guarantees that all values written to stdout cleanly match the derived structural layout specification parameters.

Golden Schema Verification Gates

To prevent unintentional API breaks, the build system automatically tracks and asserts all CLI schemas using an automated test integration sub-suite called cli-goldens located at:

//src/developer/ffx/tests/cli-goldens/

When fields are altered, added, or modified inside a plugin's argument or output structures, the build system generates the dynamic actual schemas and asserts them against the source Goldens under cli-goldens/goldens/ffx/. Mismatches will instantly halt the build process, requiring explicit developer review and synchronization acknowledgement commands:

cp out/default/host_x64/obj/src/developer/ffx/tests/cli-goldens/goldens/... <source_tree_path>

This double-check mechanism ensures complete schema governance health across the repository tree.