beads/docs/JSON_SCHEMA.md
Kevin Glynn 0d4b979354
feat: JSON schema contract, bd ping, structured errors, import enhancements (#3368)
* feat: add schema_version to all --json output (beads-5uh)

All bd commands that emit --json output now include a schema_version
field so consumers (Jawnt MCP, BeadsX, gt mail, sync scripts) can
detect format changes without silently breaking.

- Object output: schema_version injected as top-level field
- Array output: wrapped as {"schema_version": 1, "items": [...]}
- Error output: schema_version added to stderr JSON

Central implementation in outputJSON() via wrapWithSchemaVersion()
means all 272 call sites get the field automatically.

Includes:
- Unit tests for wrapping logic (object, struct, slice, nil, roundtrip)
- Updated protocol contract tests for new envelope format
- New schema_version presence test across list/ready/show
- docs/JSON_SCHEMA.md documenting the field contract per command

* feat: add ready/blocked JSON contract tests (beads-clt)

bd ready --json and bd blocked --json already return full issue objects
with dependency counts and blocked_by fields. Add protocol contract
tests to pin this behavior:

- TestJSONContract_ReadyOutputHasFullObjects: verifies dependency_count,
  dependent_count fields on ready items
- TestJSONContract_BlockedOutputHasBlockedBy: verifies blocked_by and
  blocked_by_count fields on blocked items

Update docs/JSON_SCHEMA.md with blocked output contract.

* feat: add bd ping lightweight health-check command (beads-8cc)

New minimal command that confirms bd can reach its database:
1. Resolves the .beads workspace
2. Opens the store (embedded or server)
3. Runs a trivial query (SearchIssues with Limit=1)
4. Reports timing breakdown

Supports --json for structured output with resolve_ms, store_ms,
query_ms, and total_ms fields. Exit 0 on success, 1 on failure.

Registered as read-only command (no auto-push, no file writes).
Includes protocol contract test for JSON output.

* feat: structured JSON errors on stderr when --json active (beads-06n)

All fatal error functions (FatalError, FatalErrorWithHint,
FatalErrorRespectJSON, FatalErrorWithHintRespectJSON) now emit
structured JSON with schema_version when --json is active:

  {"schema_version": 1, "error": "message", "hint": "optional"}

Centralized via jsonStderrError() and jsonStdoutError() helpers.
Replaces ad-hoc json.MarshalIndent calls scattered across error
functions with a consistent, schema-versioned format.

Includes unit tests and updated protocol contract test verifying
schema_version presence in error JSON output.

* feat: enhance bd import with stdin, --dedup, --json (beads-c6i)

Enhance the existing bd import command for bulk JSONL ingest:

- Stdin support: bd import - reads JSONL from stdin for piped workflows
- --dedup flag: skips lines whose title matches an existing open issue
  (case-insensitive) to prevent duplicate creation
- --json flag: structured output with created/skipped counts and IDs

Refactored import to use runImportFromReader() for unified file/stdin
handling. Added filterDuplicatesByTitle() for dedup logic. Updated
docs/JSON_SCHEMA.md with import output contract.

Backward compatible: existing bd import [file] and --dry-run work
exactly as before.

* fix: update tests for schema_version envelope in JSON output

Three test files expected raw JSON arrays or map[string]string, which
broke when schema_version (a number) was added to the output envelope:

- ado_test.go: parse envelope with items array instead of raw []json.RawMessage
- bootstrap_embedded_test.go: use map[string]interface{} for mixed types
- where_embedded_test.go: same map[string]interface{} fix

* fix: drop array envelope wrapping to fix 200+ test failures

The schema_version envelope was wrapping arrays as
{"schema_version": N, "items": [...]} which broke every integration
test that parses --json array output. Objects (show, create, ping)
still get schema_version injected. Arrays (list, ready, blocked)
now pass through unchanged for backwards compatibility.

Also fixes: gofmt on import.go, doc-flags reference to bd import,
uses importIssuesCore result to satisfy unparam lint.

* fix: update remaining tests for schema_version number field

config_embedded_test.go, kv_embedded_test.go, config_nodb_embedded_test.go,
and show_test.go all parsed JSON output into map[string]string but
schema_version is a number. Parse to map[string]interface{} and
skip/assert schema_version appropriately.

---------

Co-authored-by: kev <kglynn@pryoninc.com>
2026-04-20 21:09:48 -07:00

3.7 KiB

JSON Output Schema Contract

Commands that return a single object (show, create, close, ping, etc.) include a schema_version field at the top level. Commands that return arrays (list, ready, blocked, etc.) output a raw JSON array for backwards compatibility.

Schema Version

Current version: 1

The schema_version field is an integer that increments when:

  • Fields are added, renamed, or removed
  • Output structure changes (e.g., nesting depth)
  • Field types change (e.g., string to integer)

Additive changes (new optional fields) do NOT bump the version.

Output Formats

Object commands (show, create, close, update, etc.)

Commands that return a single issue or result emit a JSON object with schema_version as a top-level field alongside the data:

{
  "schema_version": 1,
  "id": "beads-abc",
  "title": "Example issue",
  "status": "open",
  "priority": 1,
  "issue_type": "task",
  "created_at": "2026-04-20T12:00:00Z"
}

List commands (list, ready, search, stale, etc.)

Commands that return multiple items emit a raw JSON array:

[
  {"id": "beads-abc", "title": "First", ...},
  {"id": "beads-def", "title": "Second", ...}
]

Error output (stderr)

Errors with --json active emit JSON to stderr:

{
  "schema_version": 1,
  "error": "issue not found: beads-xyz",
  "code": "not_found"
}

Field Contracts by Command

bd list --json

Required fields per item:

  • id (string): Issue ID (e.g., "beads-abc")
  • title (string): Issue title
  • status (string): open, in_progress, closed, deferred
  • priority (number): 0-4
  • issue_type (string): bug, feature, task, epic, chore
  • created_at (string): RFC3339 timestamp

Optional fields:

  • description, owner, updated_at, closed_at
  • labels (string[]): Attached labels
  • dependencies (object[]): Dependency records
  • dependency_count, dependent_count, comment_count (number)
  • parent (string|null): Parent issue ID

bd ready --json

Same schema as bd list --json. Items are filtered to unblocked issues only. Each item includes dependency_count, dependent_count, comment_count, and optional parent fields.

bd blocked --json

Returns issues that are blocked by unresolved dependencies. Each item includes all standard issue fields plus:

  • blocked_by_count (number): Number of blocking dependencies
  • blocked_by (string[]): IDs of blocking issues

bd show --json

Returns a single object (not wrapped in items). Same required fields as list items, plus:

  • description (string)
  • acceptance_criteria (string)
  • dependencies (object[]): Full dependency records
  • comments (object[]): Comment thread

import --json

Returns a summary object when --json is active:

  • source (string): File path or "stdin"
  • created (number): Issues created
  • skipped (number): Issues skipped (dedup)
  • dedup_skipped (number): Issues skipped by --dedup title match
  • memories (number): Memory records imported
  • ids (string[]): IDs of created issues
  • dry_run (boolean): Whether --dry-run was active

bd export --json

Outputs JSONL (one JSON object per line), not wrapped in an envelope. Each line is a self-contained issue or memory record. schema_version is included per line.

Consumer Guidelines

  1. Check schema_version on object output. If the version is higher than expected, log a warning but attempt to parse anyway (additive changes are backward-compatible).

  2. For list commands, parse the output as a JSON array directly.

  3. Ignore unknown fields. New fields may be added without bumping the schema version.

  4. Use --json flag, not --format json. The --json flag is the stable contract; --format is for human-readable variants.