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

[github-actions[bot]]

Go Fan Report: github.com/santhosh-tekuri/jsonschema/v6

Module Overview

The santhosh-tekuri/jsonschema library is a comprehensive JSON Schema validator for Go that provides robust validation with excellent error reporting. It supports all JSON Schema drafts from draft-04 through draft/2020-12, making it one of the most complete JSON Schema implementations available for Go.

This library is critical to gh-aw's validation infrastructure, providing schema validation for:

• GitHub Actions workflow files
• MCP tools configuration
• Main workflow and included file frontmatter
• Error location tracking for precise user feedback

Current Usage in gh-aw

Files Using This Module (5 files)

• pkg/workflow/schema_validation.go - GitHub Actions workflow schema validation
• pkg/workflow/safe_outputs_tools_schema_test.go - MCP tools schema validation tests
• pkg/parser/schema.go - Main workflow and included file frontmatter validation
• pkg/parser/json_path_locator.go - JSON path extraction from validation errors
• pkg/parser/json_path_locator_test.go - JSON path locator tests

Key APIs Used

• jsonschema.NewCompiler() - Creating schema compilers
• compiler.AddResource() - Adding schema documents
• compiler.Compile() - Compiling schemas
• schema.Validate() - Validating instances
• ValidationError.Causes - Detailed error iteration

Current Pattern: Cached Schema Compilation

The codebase uses an effective pattern of compiling schemas once and caching them with sync.Once:

var (
    compiledSchemaOnce sync.Once
    compiledSchema     *jsonschema.Schema
    schemaCompileError error
)

func getCompiledSchema() (*jsonschema.Schema, error) {
    compiledSchemaOnce.Do(func() {
        compiler := jsonschema.NewCompiler()
        // ... compile schema once
    })
    return compiledSchema, schemaCompileError
}

This is excellent - schema compilation is expensive and should only happen once!

Research Findings

Repository Health

• Latest Version: v6.0.2 (released May 23, 2025)
• Status: Actively maintained with regular updates
• Compliance: Passes official JSON-Schema-Test-Suite for all supported drafts
• CLI Tool: jv v0.7.0 available for standalone validation

Key Features

• ✅ Full JSON Schema compliance (draft-04 through draft/2020-12)
• ✅ Mixed dialect support (v6.0.0+)
• ✅ Custom vocabulary support via $vocabulary
• ✅ Format assertions (uuid, email, ipv4/6, date-time, semver, etc.)
• ✅ Content assertions (base64 encoding, JSON media types)
• ✅ Introspectable error hierarchy
• ✅ Multiple output formats (flag, basic, detailed)
• ✅ Localization support for ValidationError

Recent Updates (v6.0.0 → v6.0.2)

v6.0.2 (May 2025) - Maintenance release
v6.0.1 (June 2024)

• Fixed: RecursiveRef field misspelling
• Fixed: Missing Deprecated field in schema struct

v6.0.0 (June 2024) - Major release

• NEW: Mixed dialect support
• NEW: Custom $vocabulary support
• NEW: semver format validator
• NEW: Localization support for ValidationError
• Enhanced CLI with stdin support, TLS options, quiet mode

Best Practices from Maintainers

1. Compile schemas once and reuse (compilation is expensive) ✅ Already doing this!
2. Use ValidationError.Causes for detailed error reporting ✅ Already doing this!
3. Enable format assertions with compiler.AssertFormat() ❌ Not doing this
4. Enable content assertions with compiler.AssertContent() ❌ Not doing this
5. Register custom formats/encodings for domain-specific validation ❌ Not doing this

Improvement Opportunities

🏃 Quick Wins (High Impact, Low Effort)

1. Enable Format Assertions

Current: No explicit format assertion mode enabled
Benefit: Catch format violations (email, date-time, uuid) in workflow schemas
Action: Add compiler.AssertFormat() in compileSchema() (pkg/parser/schema.go:183)

func compileSchema(schemaJSON, schemaURL string) (*jsonschema.Schema, error) {
    compiler := jsonschema.NewCompiler()
    compiler.AssertFormat() // ← Add this!
    // ...
}

Impact: Would catch invalid formats in workflow configuration immediately

2. Enable Content Assertions

Current: No content assertion mode enabled
Benefit: Validate base64 encoding and JSON content in string fields
Action: Add compiler.AssertContent() for schemas with contentEncoding/contentMediaType

Impact: Better validation of embedded JSON in workflow YAML

3. Eliminate Double JSON Marshal/Unmarshal

Current: validateWithSchema() marshals to JSON and unmarshals for normalization (pkg/parser/schema.go:297-305)
Issue: Unnecessary performance overhead (2x round-trip)
Better: Pass data in correct format from the start or use jsonschema.UnmarshalJSON()

Performance Impact: ~2x improvement in validation hot path

✨ Feature Opportunities (High Impact, Medium Effort)

4. Leverage Detailed Error Output

Current: Only using basic error messages from cause.Error()
Opportunity: Use structured error output (flag/basic/detailed modes) for better debugging
Action: Implement custom error formatting using ValidationError hierarchy

Example: Show validation path AND schema location for clearer error messages

5. Add Custom Formats for Workflow-Specific Types

Opportunity: Register custom format validators for workflow patterns
Examples:

• workflow-name: Validate workflow naming conventions
• cron-expression: Validate cron schedule syntax
• github-ref: Validate GitHub ref patterns (refs/heads/, refs/tags/)

Action: Create format validators and register with compiler.RegisterFormat()

compiler.RegisterFormat(&jsonschema.Format{
    Name: "cron-expression",
    Validate: validateCronExpression,
})

6. Schema Introspection for Auto-completion

Current: Manual schema navigation in navigateToSchemaPath() and extractAcceptedFieldsFromSchema()
Opportunity: Use compiled schema structure directly for more accurate suggestions
Benefit: Better IDE-like auto-completion based on actual schema structure

📐 Best Practice Alignment (Medium Impact)

7. Consolidate Error Message Cleaning

Current: Multiple string manipulation functions for error messages

• cleanJSONSchemaErrorMessage()
• rewriteAdditionalPropertiesError()

Issue: Fragile string matching and replacement
Better: Use ValidationError structure fields directly
Action: Access KeywordLocation, InstanceLocation, and error details from structured error

8. Add Schema Version Metadata

Current: No explicit draft version in schemas
Opportunity: Specify draft version with $schema field
Benefit: Explicit contract, better compatibility, clearer expectations

Action: Add to embedded schemas:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  ...
}

9. Implement Unified Schema Cache Manager

Current: Multiple sync.Once variables for different schemas
Better: Map-based caching with schema URL as key
Benefit: More scalable, easier to add new schemas

🔧 General Improvements

10. Extract Validation Error Utilities

Current: Error extraction logic scattered across files
Opportunity: Create dedicated pkg/validation/errors.go with shared utilities
Benefit: Reusable error handling, consistent formatting

11. Add Validation Performance Metrics

Opportunity: Track schema compilation and validation timing
Benefit: Identify slow schema patterns, optimize hot paths

12. Test with Official JSON Schema Test Suite

Current: Custom tests only
Opportunity: Run against JSON-Schema-Test-Suite
Benefit: Ensure compatibility, catch edge cases

Recommendations

Priority 1 (Do First - High ROI)

1. ✅ Enable format assertions (compiler.AssertFormat())
2. ✅ Enable content assertions (compiler.AssertContent())
3. ✅ Eliminate double marshal/unmarshal in validation path

Priority 2 (Next Up)

4. Consolidate error message handling using structured errors
5. Add custom format validators for workflow types (cron, github-ref)
6. Implement unified schema cache manager

Priority 3 (Future Improvements)

7. Extract validation error utilities to shared package
8. Add schema version metadata ($schema field)
9. Schema introspection for auto-completion improvements
10. Add validation performance metrics

Interesting Discovery

The library includes a semver format validator (added in v6.0.0) which could be useful for validating version strings in workflows! The library also supports custom vocabularies, which could be leveraged to create workflow-specific validation keywords.

Next Steps

The most impactful immediate improvements are:

1. Add 2 lines (compiler.AssertFormat() and compiler.AssertContent()) to enable comprehensive validation
2. Remove the double marshal/unmarshal round-trip for 2x validation performance
3. Consider custom format validators for domain-specific validation needs

These changes require minimal code but provide significant validation improvements and better error reporting for users!

---

Module Summary: specs/mods/jsonschema-v6.md
Review Date: 2025-12-01

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! 🏴‍☠️