[go-fan] Go Module Review: google/jsonschema-go

[github-actions[bot]]

🐹 Go Fan Report: github.com/google/jsonschema-go

Module Overview

github.com/google/jsonschema-go is Google's official implementation of the JSON Schema specification for Go. It provides schema creation, validation (draft 2020-12 and draft-07), and automatic schema inference from Go structs with zero dependencies outside the standard library. The module is actively maintained and just released v0.3.0 in September 2025 with significant improvements.

Current Usage in gh-aw

Usage Summary

• Version: v0.3.0 (latest)
• Files: 1 implementation file, 2 test files
• Import Count: 3 imports
• Primary Use Case: Generating JSON schemas for MCP tool outputs

Key Usage Pattern

The project uses a single helper function GenerateOutputSchema[T]() in pkg/cli/mcp_schema.go that wraps jsonschema.ForType() to generate schemas from Go types. The generated schemas are used to describe MCP tool output structures for LLM consumption.

Current implementation:

func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
    var zero T
    typ := reflect.TypeOf(zero)
    schema, err := jsonschema.ForType(typ, &jsonschema.ForOptions{})
    return schema, err
}

Files using this module:

• pkg/cli/mcp_schema.go:7 - Implementation
• pkg/cli/mcp_schema_test.go - Comprehensive unit tests
• pkg/cli/mcp_tool_schemas_test.go - Integration tests

APIs Utilized

• ✅ jsonschema.ForType() - Schema inference from reflect.Type
• ✅ jsonschema.Schema - Core schema structure
• ✅ jsonschema.ForOptions - Configuration (currently empty)
• ❌ jsonschema.For[T]() - Not used (but should be!)
• ❌ Schema validation features - Not utilized
• ❌ TypeSchemas customization - Not configured
• ❌ Default value application - Not used

Research Findings

Repository & Maintenance

• Repository: https://github.com/google/jsonschema-go
• Latest Release: v0.3.0 (September 22, 2025)
• Activity: Actively maintained, 20 commits in past 3 months
• Open Issues: 13 (mix of bugs and enhancements)
• Contributors: Google engineers + community

Recent Updates (v0.2.0 → v0.3.0)

Breaking Changes

• TypeSchemas key changed from any to reflect.Type - prevents issues with unmappable types
• Struct validation removed - must marshal to JSON first (addresses fundamental limitations)

New Features

• Draft-07 support - Added compatibility with older JSON Schema draft
• Better error messages - Improved feedback for additionalProperties violations
• Embedded struct handling - Custom schemas for embedded types now supported

Bug Fixes

• Faster validation performance (false schema optimization)
• Nullable type support for pointer fields with custom TypeSchemas
• Nested subschema defaults application
• Nil options handling in ForType

Community Requests & Open Issues

The active issue tracker reveals important community needs:

High Priority:

1. Concurrent download of 10 logs at a time #53: Rich error reporting with JSONPath to validation failures
2. next text only for admin/maintain #48: Null support for slice types (not just pointers)
3. #37: Global TypeSchemas registry (avoid repetition)
4. Tweaks to docs, gh aw help and notice #47: Extended jsonschema tags (minlength, pattern, etc.)

Medium Priority:
5. #46: Self-referential structures (currently causes cycle errors)
6. #24: Auto-set $schema during marshaling
7. #20: Simplify verbose validation errors
8. #15: PropertyOrder control for JSON rendering
9. #13: Expose True()/False() schema constructors

Best Practices from Maintainers

Based on documentation and issue discussions:

1. Use ForT over ForType() for cleaner type-safe inference
2. Leverage TypeSchemas for custom type mappings (time.Time, UUID, etc.)
3. Use jsonschema tags for descriptions (improves LLM comprehension)
4. Avoid cycles in struct definitions (not yet supported)
5. Pointer fields = nullable - automatic ["null", "type"] generation
6. Validate after inference - use Resolve() then Validate() for end-to-end checks

Improvement Opportunities

🏃 Quick Wins

1. Simplify GenerateOutputSchema Implementation

   • Current: 5 lines with manual reflect.TypeOf
   • Better: 1 line using jsonschema.For[T](nil)
   • Impact: Cleaner code, one less import
   • Location: pkg/cli/mcp_schema.go:32-38

2. Add End-to-End Validation Tests

   • Current tests only verify schema structure
   • Add: Generate schema → validate sample JSON → assert success
   • Ensures schemas work correctly with real MCP data
   • Location: pkg/cli/mcp_schema_test.go

3. Document jsonschema Tag Conventions

   • Create project-wide convention for schema descriptions
   • Add examples to MCP tool struct documentation
   • Improves consistency and LLM understanding

4. Verify Nil Options Safety

   • Current code passes &jsonschema.ForOptions{}
   • After v0.3.0 fix (Add workflow: githubnext/agentics/weekly-research #43), can safely use nil
   • Minor simplification

✨ Feature Opportunities

1. Implement TypeSchemas for Custom Types

   • Map common types: UUID → string, time.Duration → string pattern
   • Create centralized pkg/cli/mcp_type_schemas.go
   • Reuse across all MCP tool schema generation
   • Impact: Consistent type handling, better validation

2. Add Schema Validation Middleware

   • Use schema.Resolve() and resolved.Validate() on tool outputs
   • Catch schema violations before sending to MCP clients
   • Improves reliability and debugging
   • New file: pkg/cli/mcp_schema_validator.go

3. Enable Default Value Application

   • Use resolved.ApplyDefaults() for MCP tool parameters
   • Automatically populate optional fields
   • Reduces boilerplate in tool handlers

4. Implement Schema Caching

   • Cache generated schemas (expensive reflection operations)
   • Use sync.Once or build-time generation
   • Performance gain: Significant for frequently-called tools

5. Enhance Schema Descriptions

   • Add rich metadata: examples, constraints, format hints
   • Improve LLM understanding of tool outputs
   • Better error messages for users

📐 Best Practice Alignment

1. Consistent jsonschema Tag Usage

   • Audit all MCP tool structs for missing descriptions
   • Enforce tag format in code review guidelines
   • Document best practices in CONTRIBUTING.md

2. Verify Nullable Field Handling

   • Review all MCP structs for pointer usage
   • Ensure nullable semantics match intent
   • Watch for slice nullability issues (next text only for admin/maintain #48)

3. Avoid Circular References

   • Design tool output types without cycles
   • Document limitation for contributors
   • Monitor Weekly Research Report - August 13, 2025: Agentic Workflows Market Analysis #46 for upstream solution

4. Structured Error Types

   • Wrap schema generation errors with context
   • Easier debugging of complex tool schemas
   • Prepare for rich error reporting (Concurrent download of 10 logs at a time #53)

🔧 General Improvements

1. Schema Generation Simplification

   Before:

   func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
       var zero T
       typ := reflect.TypeOf(zero)
       schema, err := jsonschema.ForType(typ, &jsonschema.ForOptions{})
       return schema, err
   }

   After:

   func GenerateOutputSchema[T any]() (*jsonschema.Schema, error) {
       return jsonschema.For[T](nil)
   }

2. Add Schema Test Fixtures

   • Pre-generate expected schemas as JSON
   • Store in testdata/schemas/
   • Use for regression testing and documentation

3. Schema Linting in CI

   • Check for missing descriptions
   • Validate schema completeness
   • Catch common mistakes early

4. Monitor Upstream Development

   • Tweaks to docs, gh aw help and notice #47 (extended tags) - Would simplify validation
   • #37 (global registry) - Would reduce boilerplate
   • Concurrent download of 10 logs at a time #53 (rich errors) - Better validation feedback
   • Track for potential adoption

5. Evaluate Library Consolidation

   • gh-aw uses two jsonschema libraries:
     • google/jsonschema-go (this one) - Schema generation
     • santhosh-tekuri/jsonschema/v6 - MCP SDK validation
   • Question: Is this intentional or redundant?
   • Consideration:
     • google/jsonschema-go: Better Go inference, simpler API, actively maintained by Google
     • santhosh-tekuri: More mature validation, richer features, MCP SDK dependency
   • Recommendation: Document separation of concerns OR consolidate if redundant

Recommendations

Priority 1: Immediate Actions

1. Simplify GenerateOutputSchema to use For[T]() directly
2. Add validation tests to ensure schemas work end-to-end
3. Document jsonschema tag conventions for the project

Priority 2: Short-term Enhancements

1. Create TypeSchemas mappings for custom types (UUID, Duration)
2. Implement schema caching for performance
3. Add schema validation middleware for MCP outputs
4. Clarify library separation (google vs santhosh-tekuri)

Priority 3: Long-term Considerations

1. Monitor extended tag support (Tweaks to docs, gh aw help and notice #47) - adopt when available
2. Consider global registry (#37) - reduce configuration repetition
3. Add schema linting to CI pipeline
4. Evaluate library consolidation if redundancy exists

Next Steps

1. ✅ Review GenerateOutputSchema implementation for simplification
2. ⏭️ Audit MCP tool structs for jsonschema tag coverage
3. ⏭️ Identify custom types needing TypeSchemas mappings
4. ⏭️ Clarify usage relationship with santhosh-tekuri/jsonschema/v6
5. ⏭️ Add comprehensive validation tests for generated schemas

---

Module summary saved to: specs/mods/jsonschema-go.md

Key Insight: gh-aw's current usage is minimal but correct. The module offers significant untapped potential for schema validation, custom type mapping, and performance optimization. The biggest opportunity is implementing schema validation middleware to catch errors before they reach MCP clients. Additionally, clarifying the relationship with the santhosh-tekuri jsonschema library would help maintain architectural clarity.

AI generated by Go Fan

[github-actions[bot]]

⚓ Avast! This discussion be marked as outdated by Go Fan.
🗺️ A newer treasure map awaits ye at Discussion #5271.
Fair winds, matey! 🏴‍☠️