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 <noreply@anthropic.com>
This commit is contained in:
Ellis Breen 2026-06-15 21:51:24 +01:00
commit 2bb8d2c305
2 changed files with 54 additions and 1 deletions

53
cmd/bd/schema.go Normal file
View file

@ -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)
}

2
go.mod
View file

@ -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