feat(enterprise): add JSON schema command (#167) (#298)

- Simple get command to retrieve API schema
- Useful for validation and documentation
- JMESPath query support for extracting definitions
- Comprehensive mdBook documentation

Author: joshrotenberg

crates/redisctl/src/cli.rs

@@ -1023,6 +1023,10 @@ pub enum EnterpriseCommands {
     #[command(subcommand, name = "job-scheduler")]
     JobScheduler(crate::commands::enterprise::job_scheduler::JobSchedulerCommands),
 
+    /// JSON schema operations
+    #[command(subcommand)]
+    Jsonschema(crate::commands::enterprise::jsonschema::JsonSchemaCommands),
+
     /// Log operations
     #[command(subcommand)]
     Logs(crate::commands::enterprise::logs::LogsCommands),

crates/redisctl/src/commands/enterprise/jsonschema.rs

@@ -0,0 +1,86 @@
+use anyhow::Context;
+use clap::Subcommand;
+
+use crate::{cli::OutputFormat, connection::ConnectionManager, error::Result as CliResult};
+
+#[allow(dead_code)]
+pub async fn handle_jsonschema_command(
+    conn_mgr: &ConnectionManager,
+    profile_name: Option<&str>,
+    jsonschema_cmd: JsonSchemaCommands,
+    output_format: OutputFormat,
+    query: Option<&str>,
+) -> CliResult<()> {
+    jsonschema_cmd
+        .execute(conn_mgr, profile_name, output_format, query)
+        .await
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum JsonSchemaCommands {
+    /// Get JSON schema for API validation
+    Get,
+}
+
+impl JsonSchemaCommands {
+    #[allow(dead_code)]
+    pub async fn execute(
+        &self,
+        conn_mgr: &ConnectionManager,
+        profile_name: Option<&str>,
+        output_format: OutputFormat,
+        query: Option<&str>,
+    ) -> CliResult<()> {
+        handle_jsonschema_command_impl(conn_mgr, profile_name, self, output_format, query).await
+    }
+}
+
+#[allow(dead_code)]
+async fn handle_jsonschema_command_impl(
+    conn_mgr: &ConnectionManager,
+    profile_name: Option<&str>,
+    command: &JsonSchemaCommands,
+    output_format: OutputFormat,
+    query: Option<&str>,
+) -> CliResult<()> {
+    let client = conn_mgr.create_enterprise_client(profile_name).await?;
+
+    match command {
+        JsonSchemaCommands::Get => {
+            let response: serde_json::Value = client
+                .get("/v1/jsonschema")
+                .await
+                .context("Failed to get JSON schema")?;
+
+            let output_data = if let Some(q) = query {
+                super::utils::apply_jmespath(&response, q)?
+            } else {
+                response
+            };
+
+            super::utils::print_formatted_output(output_data, output_format)?;
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_jsonschema_command_parsing() {
+        use clap::Parser;
+
+        #[derive(Parser)]
+        struct TestCli {
+            #[command(subcommand)]
+            cmd: JsonSchemaCommands,
+        }
+
+        // Test get command
+        let cli = TestCli::parse_from(["test", "get"]);
+        assert!(matches!(cli.cmd, JsonSchemaCommands::Get));
+    }
+}

crates/redisctl/src/commands/enterprise/mod.rs

@@ -13,6 +13,7 @@ pub mod database_impl;
 pub mod diagnostics;
 pub mod endpoint;
 pub mod job_scheduler;
+pub mod jsonschema;
 pub mod logs;
 pub mod logs_impl;
 pub mod migration;

crates/redisctl/src/main.rs

@@ -324,6 +324,16 @@ async fn execute_enterprise_command(
             )
             .await
         }
+        Jsonschema(jsonschema_cmd) => {
+            commands::enterprise::jsonschema::handle_jsonschema_command(
+                conn_mgr,
+                profile,
+                jsonschema_cmd.clone(),
+                output,
+                query,
+            )
+            .await
+        }
         Logs(logs_cmd) => {
             commands::enterprise::logs_impl::handle_logs_commands(
                 conn_mgr, profile, logs_cmd, output, query,

docs/src/SUMMARY.md

@@ -46,6 +46,7 @@
 - [Diagnostics](./enterprise/diagnostics.md)
 - [Endpoints](./enterprise/endpoints.md)
 - [Job Scheduler](./enterprise/job-scheduler.md)
+- [JSON Schema](./enterprise/jsonschema.md)
 - [Workflows](./enterprise/workflows.md)
 - [Raw API Access](./enterprise/api-access.md)
 

docs/src/enterprise/jsonschema.md

@@ -0,0 +1,261 @@
+# JSON Schema
+
+The JSON schema command provides access to the Redis Enterprise API schema definitions, useful for validation, documentation, and code generation.
+
+## Available Commands
+
+### Get JSON Schema
+
+Retrieve the complete JSON schema for the Redis Enterprise API:
+
+```bash
+# Get full JSON schema
+redisctl enterprise jsonschema get
+
+# Get schema as YAML
+redisctl enterprise jsonschema get -o yaml
+
+# Extract specific schema definitions
+redisctl enterprise jsonschema get -q 'definitions'
+
+# Get schema for a specific resource
+redisctl enterprise jsonschema get -q 'definitions.bdb'
+
+# List all available definitions
+redisctl enterprise jsonschema get -q 'definitions | keys(@)'
+```
+
+## Output Examples
+
+### Schema Structure
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Redis Enterprise API Schema",
+  "version": "1.0.0",
+  "definitions": {
+    "bdb": {
+      "type": "object",
+      "properties": {
+        "uid": {
+          "type": "integer",
+          "description": "Database unique ID"
+        },
+        "name": {
+          "type": "string",
+          "description": "Database name"
+        },
+        "memory_size": {
+          "type": "integer",
+          "description": "Memory limit in bytes"
+        },
+        "shards_count": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of database shards"
+        }
+      },
+      "required": ["name", "memory_size"]
+    },
+    "node": {
+      "type": "object",
+      "properties": {
+        "uid": {
+          "type": "integer",
+          "description": "Node unique ID"
+        },
+        "addr": {
+          "type": "string",
+          "format": "ipv4",
+          "description": "Node IP address"
+        }
+      }
+    }
+  },
+  "paths": {
+    "/v1/bdbs": {
+      "post": {
+        "requestBody": {
+          "$ref": "#/definitions/bdb"
+        }
+      }
+    }
+  }
+}
+```
+
+## Common Use Cases
+
+### API Validation
+
+Validate request payloads against the schema:
+
+```bash
+# Get schema for database creation
+redisctl enterprise jsonschema get -q 'definitions.bdb'
+
+# Extract required fields
+redisctl enterprise jsonschema get -q 'definitions.bdb.required'
+
+# Get property types
+redisctl enterprise jsonschema get -q 'definitions.bdb.properties | to_entries[] | {property: .key, type: .value.type}'
+```
+
+### Code Generation
+
+Generate TypeScript or other language definitions:
+
+```bash
+# Export schema for code generation
+redisctl enterprise jsonschema get -o json > redis-enterprise-schema.json
+
+# Extract definitions for specific resources
+redisctl enterprise jsonschema get -q 'definitions.{database: bdb, cluster: cluster, node: node}' > resources.json
+
+# Generate TypeScript interfaces (using external tool)
+redisctl enterprise jsonschema get | npx json-schema-to-typescript > redis-enterprise.d.ts
+```
+
+### Documentation
+
+Extract schema information for documentation:
+
+```bash
+# Get all resource definitions
+redisctl enterprise jsonschema get -q 'definitions | keys(@)' -o json
+
+# Get descriptions for properties
+redisctl enterprise jsonschema get -q 'definitions.bdb.properties | to_entries[] | {property: .key, description: .value.description}'
+
+# List all API paths
+redisctl enterprise jsonschema get -q 'paths | keys(@)'
+
+# Get operations for a path
+redisctl enterprise jsonschema get -q 'paths."/v1/bdbs" | keys(@)'
+```
+
+### Schema Discovery
+
+Explore available schemas and their structures:
+
+```bash
+# List all top-level schema properties
+redisctl enterprise jsonschema get -q 'keys(@)'
+
+# Find schemas with specific properties
+redisctl enterprise jsonschema get -q 'definitions | to_entries[] | select(.value.properties.memory_size) | .key'
+
+# Get enum values for properties
+redisctl enterprise jsonschema get -q 'definitions.*.properties.* | select(.enum) | {property: @, values: .enum}'
+
+# Find required properties across all schemas
+redisctl enterprise jsonschema get -q 'definitions | to_entries[] | {schema: .key, required: .value.required}'
+```
+
+## Integration Examples
+
+### Validation Script
+
+Create a validation script using the schema:
+
+```bash
+#!/bin/bash
+# validate-payload.sh
+
+SCHEMA=$(redisctl enterprise jsonschema get -q 'definitions.bdb')
+PAYLOAD=$1
+
+echo "$PAYLOAD" | jq --argjson schema "$SCHEMA" '
+  # Simple validation example
+  if .name == null then
+    error("name is required")
+  elif .memory_size == null then
+    error("memory_size is required")
+  else
+    .
+  end
+'
+```
+
+### OpenAPI Generation
+
+Convert to OpenAPI specification:
+
+```bash
+# Extract and format for OpenAPI
+redisctl enterprise jsonschema get -o json | jq '{
+  openapi: "3.0.0",
+  info: {
+    title: "Redis Enterprise API",
+    version: .version
+  },
+  components: {
+    schemas: .definitions
+  },
+  paths: .paths
+}' > openapi.json
+```
+
+### Schema Comparison
+
+Compare schemas across versions:
+
+```bash
+# Save current schema
+redisctl enterprise jsonschema get -o json > schema-current.json
+
+# Later, compare with new version
+redisctl enterprise jsonschema get -o json > schema-new.json
+diff <(jq -S . schema-current.json) <(jq -S . schema-new.json)
+
+# Find new properties
+jq -r '.definitions | keys(@)' schema-new.json | \
+  comm -13 <(jq -r '.definitions | keys(@)' schema-current.json | sort) -
+```
+
+## Best Practices
+
+1. **Cache Schema**: The schema doesn't change frequently, so cache it locally
+2. **Version Control**: Store schema snapshots in version control for tracking changes
+3. **Validation**: Use the schema to validate payloads before API calls
+4. **Code Generation**: Generate client code from schema for type safety
+5. **Documentation**: Keep schema-based documentation up to date
+
+## Troubleshooting
+
+### Schema Retrieval Issues
+
+If schema retrieval fails:
+
+```bash
+# Check API connectivity
+redisctl enterprise cluster get -q 'name'
+
+# Try raw API access
+redisctl api enterprise get /v1/jsonschema
+
+# Check with curl
+curl -k -u "$REDIS_ENTERPRISE_USER:$REDIS_ENTERPRISE_PASSWORD" \
+  https://$REDIS_ENTERPRISE_URL/v1/jsonschema
+```
+
+### Schema Validation
+
+Validate that the schema is well-formed:
+
+```bash
+# Check if valid JSON
+redisctl enterprise jsonschema get | jq empty && echo "Valid JSON"
+
+# Validate schema structure
+redisctl enterprise jsonschema get | jq 'has("definitions") and has("$schema")'
+
+# Check for required sections
+redisctl enterprise jsonschema get -q '[has("definitions"), has("properties"), has("paths")] | all'
+```
+
+## Related Commands
+
+- `redisctl api enterprise` - Direct API access for testing
+- `redisctl enterprise database create` - Use schema for creating resources
+- `redisctl enterprise cluster` - Cluster configuration that follows schema