[go-fan] Go Module Review: gojsonschema

[github-actions[bot]]

🐹 Go Fan Report: github.com/xeipuuv/gojsonschema

The gojsonschema module is currently used for JSON Schema validation of campaign specifications in gh-aw. After deep analysis, I've discovered a critical finding: this library is unmaintained AND we're already using a better alternative elsewhere in the codebase!

🚨 Critical Finding: Library Duplication

gh-aw currently uses TWO different JSON Schema libraries:

• github.com/xeipuuv/gojsonschema (draft-07, unmaintained) - Used in 1 file
• github.com/santhosh-tekuri/jsonschema/v6 (draft 2020-12, actively maintained) - Used in 5 files

This creates unnecessary complexity, increases binary size, and introduces security risks from unmaintained code.

Module Overview

github.com/xeipuuv/gojsonschema is a JSON Schema validator for Go supporting draft-04, draft-06, and draft-07. It provides validation with custom formats, localization, and detailed error reporting.

Version: v1.2.0 (October 2019)
Repository Status: ⚠️ UNMAINTAINED

• Last release: 5+ years ago (October 2019)
• Last commit: June 2024 (documentation typo fix only)
• 140 open issues with zero maintainer response
• Community consensus: Project is abandoned

Current Usage in gh-aw

Single file: pkg/campaign/validation.go

The module validates CampaignSpec structs against an embedded JSON schema (campaign_spec_schema.json) to ensure campaign configurations are valid before processing.

Usage Pattern:

1. Load embedded schema from embed.FS
2. Marshal Go struct to JSON
3. Create loaders for schema and document
4. Validate using gojsonschema.Validate()
5. Format errors for user display

Test Coverage: Excellent - 13 comprehensive test cases covering edge cases

Research Findings

Repository Health 🔴

• Stars: 2,723 (popular but stagnant)
• Last Release: v1.2.0 (October 15, 2019)
• Open Issues: 140 (most unanswered since 2020+)
• Maintainer Activity: None since 2020
• Community Status: Multiple issues asking "Is this maintained?" ([Custom Engine Test] Test Issue Created by Custom Engine #344)

Key Limitations

❌ No support for draft 2019-09 or 2020-12
❌ Unmaintained for 5+ years
❌ Confusing error messages for anyOf/oneOf (#214)
❌ No response to security or feature requests
❌ Multiple users reporting they've migrated away

What It Does Well

✅ Draft-04/06/07 support works correctly
✅ Custom format checkers
✅ Detailed error context
✅ No known security vulnerabilities in current version

Improvement Opportunities

🏃 Quick Win #1: Consolidate to santhosh-tekuri/jsonschema/v6

Impact: HIGH 🔴
Effort: Low (1-2 hours)
Priority: IMMEDIATE

Why:

1. ✅ Already using it: pkg/workflow/ and pkg/parser/ use santhosh-tekuri/jsonschema/v6
2. ✅ Actively maintained: Latest commit December 2024
3. ✅ Modern: Supports draft 2020-12
4. ✅ Better performance: Optimized compilation with caching
5. ✅ Same pattern: Workflow validation already uses it successfully
6. ✅ Feature parity: All gojsonschema features we use are available

Migration Example:

// BEFORE (xeipuuv/gojsonschema)
schemaLoader := gojsonschema.NewBytesLoader(schemaData)
documentLoader := gojsonschema.NewBytesLoader(specJSON)
result, err := gojsonschema.Validate(schemaLoader, documentLoader)

// AFTER (santhosh-tekuri/jsonschema/v6) - matches workflow validation pattern
compiler := jsonschema.NewCompiler()
var schemaDoc any
json.Unmarshal(schemaData, &schemaDoc)
compiler.AddResource("campaign-spec.json", schemaDoc)
schema, err := compiler.Compile("campaign-spec.json")

var specData any
json.Unmarshal(specJSON, &specData)
err := schema.Validate(specData)

Benefits:

• 🗑️ Remove unmaintained dependency
• 🎯 Consistent API across entire codebase
• 🛡️ Better security posture
• 📦 Smaller binary size
• 🚀 Modern JSON Schema features available
• 🔧 Easier maintenance (one library to learn)

📐 Best Practice #2: Add Schema Caching

Current: Schema is loaded from embed.FS and compiled on every validation call

Better: Follow the pattern used in pkg/workflow/schema_validation.go:

var (
    campaignSchemaOnce sync.Once
    campaignSchema     *jsonschema.Schema
    schemaCompileError error
)

func getCampaignSchema() (*jsonschema.Schema, error) {
    campaignSchemaOnce.Do(func() {
        // Compile schema once, reuse forever
        schemaData, _ := campaignSpecSchemaFS.ReadFile("schemas/campaign_spec_schema.json")
        compiler := jsonschema.NewCompiler()
        var schemaDoc any
        json.Unmarshal(schemaData, &schemaDoc)
        compiler.AddResource("campaign-spec.json", schemaDoc)
        campaignSchema, schemaCompileError = compiler.Compile("campaign-spec.json")
    })
    return campaignSchema, schemaCompileError
}

Impact: Minor performance improvement, but excellent for consistency with workflow validation

🔧 General Code Improvements

1. Enhanced Error Messages

   • Consider adding schema constraint details to errors
   • Include helpful hints for common mistakes

2. Documentation

   • Add examples of valid/invalid campaign specs in docstrings
   • Document schema evolution strategy

Recommendations

Priority 1: Migrate to santhosh-tekuri/jsonschema/v6 🔴

Why now:

1. Security: Unmaintained code is a security liability
2. Simplicity: One library > two libraries
3. Easy: Only 1 file needs changes
4. Low risk: Excellent test coverage exists
5. Consistency: Match existing workflow validation pattern

Steps:

1. Update pkg/campaign/validation.go (~50 lines)
2. Verify all tests pass (should be seamless)
3. Remove github.com/xeipuuv/gojsonschema from go.mod
4. Optional: Add schema caching like workflow validation

Estimated Effort: 1-2 hours
Risk: Very low (comprehensive tests + proven alternative)

Priority 2: Document Decision (If Migration Deferred)

If migration must wait, add a comment to validation.go:

// NOTE: This file uses xeipuuv/gojsonschema instead of santhosh-tekuri/jsonschema/v6
// (used elsewhere in the codebase) for legacy reasons. Migration is tracked in #XXXX.

However, this is NOT recommended because:

• Unmaintained dependencies accumulate technical debt
• Binary bloat from duplicate libraries
• API inconsistency makes codebase harder to learn
• Security risks increase over time

Next Steps

1. ✅ Reviewed module - Complete
2. ✅ Saved summary - specs/mods/gojsonschema.md
3. 🎯 Recommended action - Migrate to santhosh-tekuri/jsonschema/v6
4. 📋 Create issue - Track migration work
5. 🔄 Implement - Update validation.go and tests

---

Module Summary: specs/mods/gojsonschema.md
Generated by: Go Fan 🐹
Review Date: 2025-12-14

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

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

#6405

[github-actions[bot]]

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