Generate commands.schema.json for per-command success validation

.github/workflows/ci.yml

@@ -48,8 +48,11 @@ jobs:
         with:
           go-version: "1.25"
       - run: go run ./tools/gen-docs
+      - run: go run ./tools/gen-json-schemas
       - run: git diff --exit-code docs/commands
+      - run: git diff --exit-code docs/json-schema/v1/commands.schema.json
       - run: test -z "$(git status --porcelain -- docs/commands)"
+      - run: test -z "$(git status --porcelain -- docs/json-schema/v1/commands.schema.json)"
 
   chocolatey:
     name: Chocolatey package

cmd/help_json.go

@@ -84,9 +84,10 @@ type jsonCommandExample struct {
 }
 
 type jsonCommandSchemaRefs struct {
-	SuccessSchema   string `json:"success_schema"`
-	ErrorSchema     string `json:"error_schema"`
-	CommandContract string `json:"command_contract,omitempty"`
+	SuccessSchema        string `json:"success_schema"`
+	ErrorSchema          string `json:"error_schema"`
+	CommandContract      string `json:"command_contract,omitempty"`
+	CommandSuccessSchema string `json:"command_success_schema,omitempty"`
 }
 
 type jsonCommandStdinStdout struct {

cmd/help_json_test.go

@@ -291,6 +291,9 @@ func TestJSONHelpManifestV1MachineFields(t *testing.T) {
 	if put.SchemaRefs.CommandContract != "docs/json-schema/v1/commands.json#/commands/put" {
 		t.Fatalf("put command_contract = %q", put.SchemaRefs.CommandContract)
 	}
+	if put.SchemaRefs.CommandSuccessSchema != "docs/json-schema/v1/commands.schema.json#/$defs/command_put" {
+		t.Fatalf("put command_success_schema = %q", put.SchemaRefs.CommandSuccessSchema)
+	}
 	if len(put.Examples) == 0 {
 		t.Fatal("put examples = empty, want examples")
 	}
@@ -499,6 +502,18 @@ func TestJSONHelpManifestRegistryAudit(t *testing.T) {
 				t.Errorf("%s command contract file %q is not readable: %v", path, commandManifestContractFile, err)
 			}
 		}
+		if manifest.SupportsStructuredOutput && manifest.SchemaRefs.CommandSuccessSchema == "" {
+			t.Errorf("%s supports structured output but has no command success schema ref", path)
+		}
+		if manifest.SchemaRefs.CommandSuccessSchema != "" {
+			wantPrefix := commandManifestCommandSchema + "#/$defs/command_"
+			if !strings.HasPrefix(manifest.SchemaRefs.CommandSuccessSchema, wantPrefix) {
+				t.Errorf("%s command success schema = %q, want prefix %q", path, manifest.SchemaRefs.CommandSuccessSchema, wantPrefix)
+			}
+			if _, err := os.Stat(filepath.Join("..", commandManifestCommandSchema)); err != nil {
+				t.Errorf("%s command success schema file %q is not readable: %v", path, commandManifestCommandSchema, err)
+			}
+		}
 	}
 }
 

cmd/help_manifest.go

@@ -1,6 +1,9 @@
 package cmd
 
-import "github.com/spf13/pflag"
+import (
+	"github.com/dropbox/dbxcli/v3/internal/jsonschema"
+	"github.com/spf13/pflag"
+)
 
 const (
 	commandManifestVersion                 = "1"
@@ -9,6 +12,7 @@ const (
 	commandManifestSuccessSchema = "docs/json-schema/v1/success.schema.json"
 	commandManifestErrorSchema   = "docs/json-schema/v1/error.schema.json"
 	commandManifestContractFile  = "docs/json-schema/v1/commands.json"
+	commandManifestCommandSchema = "docs/json-schema/v1/commands.schema.json"
 )
 
 type jsonCommandManifestMetadata struct {
@@ -420,6 +424,7 @@ func commandManifestSchemaRefs(path string, supportsStructuredOutput bool) jsonC
 	if supportsStructuredOutput || path == "help" {
 		if _, ok := commandContractRegistry[path]; ok {
 			refs.CommandContract = commandManifestContractFile + "#/commands/" + path
+			refs.CommandSuccessSchema = commandManifestCommandSchema + "#/$defs/" + jsonschema.CommandDefinitionName(path)
 		}
 	}
 	return refs