src/developer/ffx/docs/json-machine-schemas.md

<!-- Copyright 2026 The Fuchsia Authors. All rights reserved. -->
<!-- Use of this source code is governed by a BSD-style license that can be -->
<!-- found in the LICENSE file. -->

# 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:

```sh
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:

```rust
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:

```rust
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:

```sh
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.