From 2bb8d2c30583c03cd5396cd351601fdfcfadf3c6 Mon Sep 17 00:00:00 2001 From: Ellis Breen <1263585+griels@users.noreply.github.com> Date: Mon, 15 Jun 2026 21:51:24 +0100 Subject: [PATCH] Add `bd schema` command emitting JSON Schema for output records `bd schema` reflects the canonical issue/dependency output structs (internal/types) into a JSON Schema via invopop/jsonschema, so consumers can codegen typed models (datamodel-code-generator, quicktype, ...) instead of hand-mirroring the --json / export format. Because the schema is generated from the same structs bd serializes, it cannot drift from the actual output the way docs/JSON_SCHEMA.md or a downstream consumer model (e.g. beads-mcp's Pydantic models) can. Output carries schema_version (== JSONSchemaVersion). Promotes invopop/jsonschema from an indirect to a direct dependency. Co-Authored-By: Claude Opus 4.8 --- cmd/bd/schema.go | 53 ++++++++++++++++++++++++++++++++++++++++++++++++ go.mod | 2 +- 2 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 cmd/bd/schema.go diff --git a/cmd/bd/schema.go b/cmd/bd/schema.go new file mode 100644 index 000000000..ab998284f --- /dev/null +++ b/cmd/bd/schema.go @@ -0,0 +1,53 @@ +package main + +import ( + "github.com/invopop/jsonschema" + "github.com/spf13/cobra" + + "github.com/steveyegge/beads/internal/types" +) + +// schemaCmd emits the JSON Schema for bd's canonical --json / export output +// record types. +// +// The schema is generated by reflection from the same internal/types structs +// that bd serializes, so by construction it cannot drift from the actual output +// the way a hand-maintained doc (docs/JSON_SCHEMA.md) or a downstream consumer +// model (e.g. beads-mcp's Pydantic models) can. The emitted schema_version +// matches JSONSchemaVersion and bumps with it. +// +// Consumers can codegen typed models from this output (datamodel-code-generator +// for Python/Pydantic, quicktype, etc.) instead of hand-mirroring the format. +var schemaCmd = &cobra.Command{ + Use: "schema", + Short: "Print the JSON Schema for bd's --json / export output", + Long: `Print the JSON Schema for bd's canonical output record types. + +The schema is reflected from the same Go structs bd serializes, so it stays in +lockstep with the actual --json / export output. Use it to generate typed +consumer models (datamodel-code-generator, quicktype, ...) rather than +hand-maintaining them. + + bd schema | jq '.types.issue' # the issue record schema + bd schema | jq '.types.dependency' # the dependency record schema`, + Run: func(cmd *cobra.Command, args []string) { + // Inline referenced types so each record schema is self-contained and + // directly consumable by codegen tools. + reflector := &jsonschema.Reflector{DoNotReference: true} + + doc := map[string]interface{}{ + "schema_version": JSONSchemaVersion, + "types": map[string]*jsonschema.Schema{ + "issue": reflector.Reflect(&types.Issue{}), + "dependency": reflector.Reflect(&types.Dependency{}), + }, + } + // Raw: the document carries its own schema_version; do not double-wrap + // it in the --json envelope. + outputJSONRaw(doc) + }, +} + +func init() { + rootCmd.AddCommand(schemaCmd) +} diff --git a/go.mod b/go.mod index d24eae88d..2f66e9e76 100644 --- a/go.mod +++ b/go.mod @@ -13,6 +13,7 @@ require ( github.com/cenkalti/backoff/v4 v4.3.0 github.com/dolthub/driver/v2 v2.1.4 github.com/go-sql-driver/mysql v1.9.3 + github.com/invopop/jsonschema v0.13.0 github.com/olebedev/when v1.1.0 github.com/spf13/cobra v1.10.2 github.com/spf13/viper v1.21.0 @@ -41,7 +42,6 @@ require ( github.com/cenkalti/backoff/v5 v5.0.3 // indirect github.com/cockroachdb/apd/v3 v3.2.3 // indirect github.com/fsnotify/fsnotify v1.9.0 // indirect - github.com/invopop/jsonschema v0.13.0 // indirect github.com/mailru/easyjson v0.7.7 // indirect github.com/moby/moby/api v1.54.1 // indirect github.com/moby/moby/client v0.4.0 // indirect