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

[github-actions[bot]]

🐹 Go Fan Report: google/jsonschema-go

🎯 Perfect Timing: v0.4.0 Released Yesterday!

Today's review analyzes github.com/google/jsonschema-go - and we caught it at the perfect moment! Version v0.4.0 was released yesterday (December 17, 2025) with significant new features and bug fixes.

Module Overview

google/jsonschema-go is Google's official JSON Schema implementation for Go, maintained by the core Go team. It provides schema inference from Go types, validation against JSON Schema specifications (draft 2020-12 and draft-07), and zero-dependency operation using only the Go standard library.

Key Characteristics:

• 🏢 Maintained by Google's Go team (@jba, @samthanawalla, @findleyr)
• ⭐ 167 stars
• 📦 Zero dependencies outside Go standard library
• 🔄 Supports both JSON Schema draft 2020-12 and draft-07
• 📅 Updated yesterday with v0.4.0 release

Current Usage in gh-aw

Minimal but Strategic:

• Files: 1 file (pkg/cli/mcp_schema.go)
• Purpose: Schema generation helper for MCP tool outputs
• Status: Currently prepared for future use - not actively used in production yet

Implementation:

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

Test Coverage:

• ✅ Excellent test coverage demonstrating correct schema generation
• ✅ Tests for LogsData, AuditData, WorkflowStatus types
• ✅ Validates schema structure and properties
• ✅ Confirms schemas marshal to JSON correctly

🚀 What's NEW in v0.4.0 (Released Yesterday!)

PropertyOrder Feature (#51)

PERFECT for gh-aw! Schemas now include PropertyOrder field for deterministic property ordering. This aligns perfectly with gh-aw's workflow YAML generation needs where field order matters.

type Player struct {
    Name   string `json:"name"`
    Scores []int  `json:"scores"`
}
// PropertyOrder will be: ["name", "scores"]

Full Draft-07 Support (#50)

• Separate dependencies field handling
• Separate id and anchor behavior
• Ignore other properties of $ref objects
• Better compatibility with legacy systems

Critical Bug Fixes

Nullable Types for Slices (#49)

Slices now correctly include null type alongside array type:

{"type": ["null", "array"], "items": {"type": "string"}}

Nullable Types for Non-Native Pointers (#42)

Fixed handling of *time.Time and similar pointer types to properly include null.

JSON Marshal Consistency (#52)

Fixed marshaling bugs by using value receiver for Schema.MarshalJSON().

Other Fixes

• Nested defaults application (Test coverage console formatting august 13 #38)
• Embedded struct custom schema handling (Make test-*.md workflows self-contained by removing @include directives #32)
• Integer range limits for int8, uint8, int16, uint16, etc. (Remove mentions of ai-inference and genaiscript from CLI #30)

Research Findings

API Design (Excellent)

Preferred Pattern:

// Use generic For[T]()
schema, err := jsonschema.For[MyStruct](nil)

With Custom Types:

opts := &jsonschema.ForOptions{
    TypeSchemas: map[reflect.Type]*jsonschema.Schema{
        reflect.TypeFor[uuid.UUID](): {Type: "string"},
        reflect.TypeFor[time.Duration](): {Type: "string"},
    },
}
schema, err := jsonschema.For[MyStruct](opts)

Struct Tags:

type Output struct {
    Name string `json:"name" jsonschema:"Name of the user"`
    Age  int    `json:"age,omitempty" jsonschema:"Age in years"`
}

Validation Pattern

// 1. Resolve schema
resolved, err := schema.Resolve(&jsonschema.ResolveOptions{
    ValidateDefaults: true,
})

// 2. Validate JSON value
var data map[string]any
json.Unmarshal(jsonBytes, &data)
err = resolved.Validate(data)

Comparison with santhosh-tekuri/jsonschema/v6

gh-aw uses both JSON schema libraries:

• google/jsonschema-go: Schema generation (inference from Go types)
• santhosh-tekuri/jsonschema/v6: Schema validation (validate data against schemas)

Different use cases, complementary tools:

• Use google/jsonschema-go for: Generating schemas from Go structs
• Use santhosh-tekuri/jsonschema/v6 for: Validating JSON against schemas

No conflict - they serve different purposes!

Improvement Opportunities

🏃 Quick Wins (Implement This Week)

1. UPGRADE to v0.4.0 (URGENT)

Effort: 5 minutes | Impact: HIGH | Risk: VERY LOW

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

Why now:

• ✅ Released yesterday with important features
• ✅ PropertyOrder aligns with gh-aw's deterministic needs
• ✅ Critical bug fixes for nullable types
• ✅ Draft-07 support for broader compatibility
• ✅ No breaking changes from v0.3.0

2. Simplify GenerateOutputSchema

Effort: 2 minutes | Impact: LOW | Risk: NONE

Current implementation:

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

Recommended (more idiomatic):

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

Benefits:

• Cleaner (3 lines → 1 line)
• No reflect.TypeOf indirection
• More idiomatic use of the library
• Better error messages with type names

3. Add Schema Validation Test

Effort: 15 minutes | Impact: MEDIUM | Risk: NONE

Ensure generated schemas validate actual output:

func TestGeneratedSchemasValidateRealOutput(t *testing.T) {
    // Generate schema
    schema, err := GenerateOutputSchema[LogsData]()
    require.NoError(t, err)

    // Resolve schema
    resolved, err := schema.Resolve(&jsonschema.ResolveOptions{})
    require.NoError(t, err)

    // Create real output
    data := LogsData{
        Summary: "Test",
        Runs: []RunData{{WorkflowName: "test"}},
    }

    // Marshal to JSON then to map[string]any
    jsonBytes, _ := json.Marshal(data)
    var jsonValue map[string]any
    json.Unmarshal(jsonBytes, &jsonValue)

    // Validate
    err = resolved.Validate(jsonValue)
    require.NoError(t, err, "Generated schema should validate real output")
}

✨ Feature Opportunities (Future)

4. Add Custom Type Schemas for Domain Types

Effort: 30 minutes | Priority: MEDIUM

If gh-aw adds custom types like UUID or cron expressions:

var mcpSchemaOptions = &jsonschema.ForOptions{
    TypeSchemas: map[reflect.Type]*jsonschema.Schema{
        reflect.TypeFor[uuid.UUID](): {
            Type: "string",
            Description: "UUID in canonical format",
        },
        // Add other custom types as needed
    },
}

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

5. Use Schemas in Production MCP Tools

Effort: 2 hours | Priority: MEDIUM

Currently schemas are generated but not used. Consider:

• Adding output schemas to MCP tool definitions
• Helps LLMs understand expected output format
• Enables client-side validation
• Better error messages for malformed data

6. Monitor Upstream Issues

Watch these:

• Tweaks to docs, gh aw help and notice #47: Extended jsonschema tag support (minLength, pattern, etc.)
• #37: Global type schema registry
• Concurrent download of 10 logs at a time #53: Rich validation error reporting with JSONPath
• Weekly Research Report - August 13, 2025: Agentic Workflows Market Analysis #46: Self-referential struct support

Consider contributing:

• Issue Add codex test action #13: True() and False() helper functions

📐 Best Practice Alignment

7. Add Comprehensive Documentation

Add documentation explaining schema generation rules and MCP requirements:

// GenerateOutputSchema generates a JSON schema from a Go struct type for MCP tool outputs.
// The schema conforms to JSON Schema draft 2020-12 and draft-07.
//
// Schema generation rules:
//   - json tags define property names
//   - jsonschema tags define descriptions
//   - omitempty/omitzero mark optional fields
//   - Pointer types include null in their type array
//   - Slices allow null values (jsonschema-go v0.4.0+)
//
// MCP Requirements:
//   - Tool output schemas must be objects (not arrays or primitives)
//   - All properties should have descriptions for better LLM understanding
//   - Required vs optional fields must be correctly specified

Recommendations

Immediate (This Week)

1. ✅ UPGRADE to v0.4.0 - Critical fixes and PropertyOrder feature
2. ✅ Simplify GenerateOutputSchema - Use For[T]() directly
3. ✅ Add validation test - Ensure schemas validate real output

Near-Term (Next Month)

4. Consider using schemas in production MCP tools
5. Add custom TypeSchemas if domain types are introduced
6. Add comprehensive documentation

Long-Term (Future)

7. Monitor issue Tweaks to docs, gh aw help and notice #47 for extended tag support
8. Watch issue #37 for global registry feature
9. Consider contributing to upstream issues

Rating: ⭐⭐⭐⭐⭐ (5/5)

Why Excellent:

• ✅ ACTIVE: Released v0.4.0 yesterday with important features
• ✅ GOOGLE MAINTAINED: Core Go team members
• ✅ ZERO DEPENDENCIES: Only Go standard library
• ✅ DUAL SPEC SUPPORT: Draft-07 + 2020-12
• ✅ CLEAN API: Generic For[T]() function
• ✅ WELL TESTED: Includes JSON Schema Test Suite
• ✅ PERFECT TIMING: PropertyOrder feature aligns with gh-aw needs
• ✅ LOW RISK: Minimal usage makes upgrade extremely safe
• 🎯 UPGRADE NOW: v0.4.0 released yesterday!

Next Steps

1. Upgrade to v0.4.0 immediately - safe, no breaking changes
2. Simplify the helper function implementation
3. Add validation tests for round-trip testing
4. Consider enabling schemas in MCP tool definitions

---

Generated by Go Fan 🐹
Module summary saved to: specs/mods/jsonschema-go.md
Review date: December 18, 2025

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

#6835

[github-actions[bot]]

This discussion was automatically closed because it was created by an agentic workflow more than 3 days ago.