Go Module Review: google/jsonschema-go

[github-actions[bot]]

🐹 Go Fan Report: google/jsonschema-go

Module Overview

Official Google JSON Schema implementation for Go, providing schema inference from Go structs, schema construction, and validation. Supports JSON Schema draft 2020-12 and draft-07.

• Repository: https://github.com/google/jsonschema-go
• Stars: 173 ⭐
• License: MIT
• Age: Very new! (Created August 2025)
• Status: Actively developed (last update 11 days ago)

Current Usage in gh-aw

This project uses google/jsonschema-go specifically for MCP tool schema generation - converting Go struct types into JSON schemas that describe MCP tool outputs.

Files & Integration

• Files: 3 files (mcp_schema.go + 2 test files)
• Test Coverage: 679 lines of comprehensive tests
• Key APIs Used:
  • jsonschema.For[T]() - Schema inference from generics
  • Schema.Resolve() - Resolve schema references
  • Schema.Validate() - Validate JSON against schemas

Usage Pattern

// Generate schema from Go struct for MCP tool outputs
func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
    return jsonschema.For[T](nil)
}

// Add default values for better UX (SEP-1024 elicitation defaults)
func AddSchemaDefault(schema *jsonschema.Schema, propertyName string, value any) error {
    // ... manually adds Default field to properties
}

Research Findings

🆕 Recent Updates

v0.4.2 (December 19, 2025) - Latest

• 🐛 Bug fix: Empty map in Schema.Properties now serializes correctly

v0.4.0 (December 17, 2025) - Major Release

• ✨ Draft 07 Support - Added JSON Schema draft-07 compatibility
• ✨ PropertyOrder Feature - Maintains deterministic field ordering
• 🐛 Range limits for inferred integer types
• 🐛 Arrays now always accept null values
• 🐛 Value receiver for Schema.MarshalJSON (performance improvement)

v0.3.0 (September 2025) - Breaking Changes

• ⚠️ TypeSchemas key changed from any to reflect.Type
• ⚠️ Struct validation removed (fundamentally flawed)

📊 Version Status

• Current: v0.4.0
• Latest: v0.4.2
• Gap: 2 patch versions behind ⚠️

🏗️ Architectural Discovery: Dual-Library Pattern

This project demonstrates an excellent architectural pattern by using TWO complementary JSON Schema libraries:

1. google/jsonschema-go - Schema INFERENCE

   • Purpose: Generate JSON schemas FROM Go structs
   • Use case: MCP tool output schemas
   • Direction: Go → JSON Schema
   • Location: pkg/cli/mcp_schema.go

2. santhosh-tekuri/jsonschema/v6 - Schema VALIDATION

   • Purpose: Validate JSON/YAML AGAINST schemas
   • Use case: Workflow YAML validation
   • Direction: JSON/YAML + Schema → Validation
   • Location: pkg/workflow/schema_validation.go

This is smart because:

• Each library excels at its specific task
• santhosh-tekuri is mature (v6), battle-tested for validation
• google/jsonschema-go is modern, Google-backed, perfect for inference
• Zero functional overlap

Improvement Opportunities

🏃 Quick Wins

1. Update to v0.4.2 (5 minutes)

Priority: High - Simple version bump for bug fix

• Current: v0.4.0
• Latest: v0.4.2 (released December 19, 2025)
• Benefits: Fix for empty Properties map serialization
• Action: go get github.com/google/jsonschema-go@v0.4.2 && go mod tidy
• Risk: Minimal (patch version)

2. Add $schema Field to Generated Schemas (15 minutes)

Priority: Medium - Improves schema clarity

• Issue: MCP tool schemas don't declare their JSON Schema version
• Benefit: Clearer interpretation by MCP clients, better tooling support
• Recommendation: Add $schema: "https://json-schema.org/draft/2020-12/schema" to generated schemas
• Complexity: Low - single field addition to schema construction

✨ Feature Opportunities

3. Leverage PropertyOrder Feature (10 minutes)

Priority: Low - Quality of life improvement

• New in v0.4.0: PropertyOrder maintains deterministic field ordering
• Current: Already on v0.4.0 but not using PropertyOrder
• Benefits: Consistent schema output, better diffs, easier debugging
• Investigation: Determine if deterministic ordering would benefit MCP tool schemas

4. Validate Schemas Against Real MCP Output (30 minutes)

Priority: Medium - End-to-end validation

• Current: Test suite validates schemas against mock test data
• Opportunity: Add validation of actual MCP tool runtime outputs
• Benefits: Catch schema drift early, ensure accuracy
• Pattern: Already established in TestGeneratedSchemasValidateRealOutput

📐 Best Practice Alignment

5. Document Schema Tag Conventions (20 minutes)

Priority: Medium - Developer experience

• Current: Struct tags (json, jsonschema) used but not documented
• Opportunity: Add documentation for tag usage patterns
• Benefits: Consistency across MCP tools, easier onboarding
• Location: Add to mcp_schema.go or create separate guide

6. Investigate Custom Type Support (30 minutes)

Priority: Low - Depends on need

• Context: Issue #37 requests global TypeSchemas registry for custom types
• Question: Does gh-aw use custom types (time.Time, UUIDs, enums) in MCP schemas?
• Action: Audit MCP tool structs for custom types needing schema overrides
• Pattern: Use ForOptions.TypeSchemas for one-off overrides if needed

🔧 General Improvements

7. Monitor Open Issues (Ongoing awareness)

• Issue Weekly Research Report - August 13, 2025: Agentic Workflows Market Analysis #46: Self-referential structures not supported

  • Status: Open bug
  • Impact: Low (current tools don't need recursive schemas)
  • Action: Monitor if recursive MCP schemas needed in future

• Issue #37: Global TypeSchemas registry

  • Status: Enhancement request
  • Impact: Could simplify custom type handling
  • Action: Upvote if custom types become common

• Issues the compute-text step should only be lazily inserted #20, Concurrent download of 10 logs at a time #53: Better error reporting

  • Status: Requested improvements
  • Impact: Better debugging experience
  • Action: Watch for resolution if validation errors become problematic

Recommendations

✅ Priority 1: Update Module (5 min)

Update to v0.4.2 - Simple, low-risk patch update for bug fix

go get github.com/google/jsonschema-go@v0.4.2
go mod tidy

📝 Priority 2: Documentation (20 min)

Document jsonschema tag usage - Help contributors understand schema generation

Add to mcp_schema.go:

// Schema Generation Tag Guide:
//   - json:"name"           - JSON property name
//   - jsonschema:"desc"     - Property description for LLMs
//   - omitempty             - Mark field as optional
//   - Pointer types         - Include null in type array

🎯 Priority 3: Feature Enhancement (15 min)

Add $schema field - Improve schema clarity for MCP clients

👀 Priority 4: Monitoring

Watch repository - The project is very active with regular releases. Monitor for:

• New features that could benefit gh-aw
• Bug fixes and performance improvements
• Breaking changes in future major versions

Next Steps

1. ✅ Immediate: Update to v0.4.2
2. 📝 This week: Add schema tag documentation
3. 🧪 Next sprint: Consider adding $schema field
4. 👀 Ongoing: Monitor repository for relevant updates

Conclusion

The use of google/jsonschema-go in this project is well-implemented and appropriate. The module is:

• ✅ Used for the right purpose (schema inference)
• ✅ Well-tested with comprehensive test coverage
• ✅ Part of a smart dual-library architecture
• ✅ Actively maintained by Google
• ⚠️ Slightly behind (2 patch versions)

Rating: ⭐⭐⭐⭐ (4/5) - Very good implementation with minor version lag

The main action items are straightforward: update to the latest patch version and add some documentation. The architectural decision to use this for inference while using santhosh-tekuri/jsonschema for validation is exemplary.

---

Generated by Go Fan on 2025-12-30
Module summary saved to: specs/mods/google-jsonschema-go.md

AI generated by Go Fan