Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

RFC: document --json output schemas in --help and/or generated docs

オープン
  • 何か問題がありますか？
#493 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
ドキュメント
明瞭さ
説明が足りない
活発さ
静か
技術スタック
rust
領域
cli, documentation

調査の方向性

リストされている icp コマンドの既存の --help 出力から始め、docs/reference/cli.md および llms.txt と比較します。canister のステータスの扱いを含め、RFC のドキュメント方針を確定し、JSON コマンドのスキーマが一貫してドキュメント化されていることを完了条件として定義します。

索引モデルが issue の本文から書いたものです。

説明

question

Background

Many icp commands support a --json flag for machine-readable output, but --help currently says nothing about what the output looks like beyond "Output command results as JSON". For an agent (or a developer writing scripts) this means the JSON schema has to be discovered by running the command live or reading the source code.

This RFC asks: where and how should JSON output schemas be documented?

Current state

The following commands produce structured JSON output with no schema documentation in --help:

Command Schema (verified from source)
icp deploy --json {"canisters": [{"name": string, "canister_id": string, "url": string|null}]}
icp network status --json {"managed": bool, "api_url": string, "gateway_url": string|null, "root_key": string, "candid_ui_principal": string|null, "proxy_canister_principal": string|null}
icp canister call --json {"response_bytes": string, "response_text": string|null, "response_candid": string|null}
icp canister create --json {"canister_id": string, "canister_name": string|null}
icp canister list --json {"canisters": [string]}
icp canister logs --json {"log_records": [{"timestamp": u64, "index": u64, "content": string}]}
icp canister snapshot create --json {"snapshot_id": string, "taken_at_timestamp": u64, "total_size_bytes": u64}
icp canister snapshot list --json {"snapshots": [{"snapshot_id": string, "taken_at_timestamp": u64, "total_size_bytes": u64}]}
icp cycles balance --json {"balance": string}
icp cycles mint --json {"deposited": string, "new_balance": string}
icp cycles transfer --json {"block_index": string}
icp token transfer --json {"block_index": string}
icp identity list --json {"default_identity": string, "identities": [{"name": string, "principal": string}]}
icp identity new --json {"seed_phrase": string}

Note: icp canister status --json produces a more complex structure (full status object) that is not listed here as it is not a simple flat schema.

Why it matters

Two specific workflows already referenced in the icp-cli skill documentation rely on parsing JSON output without having the schema documented:

  • icp network status --json — used in dev server configuration to extract api_url and root_key
  • icp deploy --json — used to extract canister_id and url per deployed canister

An agent or script guessing field names (e.g. canisterId vs canister_id, apiUrl vs api_url) will silently get undefined/null with no error.

Options for discussion

Option A — Document schemas inline in --help

Add the schema to each --json flag description, e.g.:

--json   Output as JSON: {"canisters": [{"name": string, "canister_id": string, "url": string|null}]}

Pros: schema is right where the flag is; works offline; agents reading --help get it immediately.
Cons: verbose; schema in two places if also in generated docs; must be kept in sync manually.

Option B — Document schemas in generated CLI reference only

Keep --help terse ("Output command results as JSON") and document schemas in docs/reference/cli.md and https://cli.internetcomputer.org/llms.txt.

Pros: single source of truth; no --help clutter.
Cons: agents running --help at invocation time don't see it; requires network access to docs.

Option C — Brief note in --help pointing to docs

--json   Output as JSON. Schema documented at https://cli.internetcomputer.org/reference/cli.md

Pros: --help stays clean; agents know where to look.
Cons: requires network access; URL may change.

Option D — Standardise on a stable JSON envelope

Wrap all JSON output in a consistent {"command": "...", "data": {...}} envelope so agents can rely on the outer shape without knowing the inner schema, and document the inner schemas in generated docs.

Questions for maintainers

  1. Which option (or combination) fits best with the project's documentation philosophy?
  2. Should JSON schemas be considered a stable public API and versioned accordingly?
  3. Is icp canister status --json output intentionally undocumented given its complexity, or should it be documented too?
主要言語
Rust
スター
115
フォーク
14
平均マージ
19時間 57分
マージ済み PR（30日）
33

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

dfinity/icp-cli のほかの issue

dfinity/icp-cli の issue をすべて見る

似ている issue

Rust の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。