Skip to content

Decide whether relayctl report JSON should carry a schemaVersion #784

Description

@jeremi

The relayctl reference names a report schema, relayctl.report.v1, that has
no existence anywhere in the source tree. Either the docs name a schema that
does not exist, or the binary is missing a schemaVersion field it should
emit. Both are defensible, so this needs a decision before either is fixed.

What Happened

docs/site/src/content/docs/reference/relayctl.mdx:51 describes the --json
flag as:

The seven shared workflow commands emit relayctl.report.v1 JSON ...
tooling editor emits relayctl.editor.v1.

The second half is true. The first half names an identifier that appears
nowhere else in the repository. On main:

$ git grep -n 'relayctl\.report\.v1'
docs/site/src/content/docs/reference/relayctl.mdx:51: ...

$ git grep -n 'relayctl\.editor\.v1'
crates/registry-relayctl/src/tooling_editor.rs:168:        schema_version: "relayctl.editor.v1",
crates/registry-relayctl/tests/editor.rs:25:        assert_eq!(report["schemaVersion"], "relayctl.editor.v1");
docs/site/src/content/docs/reference/relayctl.mdx:51: ...

The two envelopes really are asymmetric. EditorSetupReport
(crates/registry-relayctl/src/tooling_editor.rs) carries a
schema_version field, and crates/registry-relayctl/tests/editor.rs
asserts it on the wire. ToolingReport
(crates/registry-relay-v2/src/tooling.rs) has exactly three fields and no
version of any kind:

pub struct ToolingReport {
    pub status: ToolingStatus,
    pub diagnostics: Vec<Diagnostic>,
    pub details: ToolingDetails,
}

A consumer reading the reference would look for a schemaVersion member in
--json output and not find one.

Expected Behavior

One of two things, whichever the product wants:

  1. The docs are right and the code is short a field. Add
    schemaVersion: "relayctl.report.v1" to the report envelope, matching the
    precedent tooling editor already sets, and assert it in
    crates/registry-relayctl/tests/cli_contract.rs.
  2. The code is right and the docs overname it. Drop the identifier from
    the reference and describe the --json output by its actual members.

Two considerations that bear on the choice, neither decisive:

  • ToolingReport is owned by registry-relay-v2, not by relayctl, so an
    identifier in the relayctl.* namespace sits on a type the tool does not
    own. relayctl.editor.v1 does not have this problem: EditorSetupReport
    is relayctl's own type.
  • Adding a member is additive, so
    products/relay-v2/scripts/test_adopter_workflow.py (which parses this
    output with json.loads) would keep passing. It is still a wire-format
    change to adopter tooling output, though relayctl sits outside the frozen
    Version 1 contract set, so versioning it is permitted.

Reproduction

git grep -n 'relayctl\.report\.v1'   # one hit, docs only

relayctl init /tmp/proj
relayctl --json check /tmp/proj | jq -c 'keys'
# ["details","diagnostics","status"]        <- no schemaVersion

relayctl --json tooling editor /tmp/proj | jq -c 'keys, .schemaVersion'
# ["files","projectDirectory","schemaVersion","status"]
# "relayctl.editor.v1"                      <- the envelope that does carry one

Environment

Observed on main. Rust 1.95.0 (the rust-toolchain.toml pin), macOS. No
feature flags involved; the seven shared workflow commands are the default
build.

Notes

Pre-existing, not introduced by any in-flight change. Found while correcting
the --json description in the same reference table; that edit deliberately
left this phrase untouched because fixing it needs this decision first.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:relayRegistry Relay ownership.documentationImprovements or additions to documentationrustRust implementation work.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions