Pin JSON schema to v0.41.1 and add validation performance metrics

[Copilot]

Schema URL pointed to main branch, risking unexpected breaking changes and non-reproducible builds. No visibility into validation performance.

Changes

Schema version pinning

• Pinned to https://raw.githubusercontent.com/github/gh-aw/v0.41.1/docs/public/schemas/mcp-gateway-config.schema.json
• Added update instructions in code comments

Performance metrics

• Added timing instrumentation for schema fetch, compilation, parsing, and validation
• Logged via config:validation_schema debug logger (zero overhead when disabled)

Example output with DEBUG=config:*:

config:validation_schema HTTP request completed in 20.47ms
config:validation_schema Schema read completed in 245µs (size: 13040 bytes)
config:validation_schema Schema fixes applied in 299µs
config:validation_schema Total schema fetch and fix completed in 21.06ms
config:validation_schema Schema compilation/retrieval took: 22.8ms
config:validation_schema JSON parsing took: 10.6µs
config:validation_schema Schema validation took: 61.7µs
config:validation_schema Total validation completed successfully in 22.9ms

Files changed: internal/config/validation_schema.go (+30, -12)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.com
  • Triggering command: /tmp/go-build1368616235/b271/launcher.test /tmp/go-build1368616235/b271/launcher.test -test.testlogfile=/tmp/go-build1368616235/b271/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true -c=4 -nolocalimports -importcfg /tmp/go-build823456307/b258/importcfg -pack /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_core.go /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_feature.go conf�� unset TqgVVKUfb .12/x64/bin/as user.email (dns block)
• invalid-host-that-does-not-exist-12345.com
  • Triggering command: /tmp/go-build1368616235/b259/config.test /tmp/go-build1368616235/b259/config.test -test.testlogfile=/tmp/go-build1368616235/b259/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true go s/internal/fips1--64 64/pkg/tool/linu-o (dns block)
• nonexistent.local
  • Triggering command: /tmp/go-build1368616235/b271/launcher.test /tmp/go-build1368616235/b271/launcher.test -test.testlogfile=/tmp/go-build1368616235/b271/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true -c=4 -nolocalimports -importcfg /tmp/go-build823456307/b258/importcfg -pack /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_core.go /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_feature.go conf�� unset TqgVVKUfb .12/x64/bin/as user.email (dns block)
• slow.example.com
  • Triggering command: /tmp/go-build1368616235/b271/launcher.test /tmp/go-build1368616235/b271/launcher.test -test.testlogfile=/tmp/go-build1368616235/b271/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true -c=4 -nolocalimports -importcfg /tmp/go-build823456307/b258/importcfg -pack /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_core.go /home/REDACTED/work/gh-aw-mcpg/gh-aw-mcpg/internal/config/config_feature.go conf�� unset TqgVVKUfb .12/x64/bin/as user.email (dns block)
• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build1368616235/b280/mcp.test /tmp/go-build1368616235/b280/mcp.test -test.testlogfile=/tmp/go-build1368616235/b280/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true 64/src/runtime/cgo 64/src/internal/bytealg/count_am--gdwarf2 ache/go/1.25.6/x64/pkg/tool/linu--64 pull.rebase bis (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[go-fan] Go Module Review: jsonschema</issue_title>
<issue_description># 🐹 Go Fan Report: santhosh-tekuri/jsonschema

Module Overview

The github.com/santhosh-tekuri/jsonschema module is a comprehensive JSON Schema validation library that supports multiple draft specifications (Draft 4, 6, 7, 2019-09, and 2020-12). It provides fast, spec-compliant validation with excellent error reporting capabilities.

Repository: https://github.com/santhosh-tekuri/jsonschema
Current Version: v5.3.1 (April 2024)
Latest Version: v6.0.2 (May 2025) ⚠️ Major upgrade available
Stars: 1,200+ | License: Apache 2.0

Current Usage in gh-aw-mcpg

Files & Import Count

This is one of our most heavily used validation modules:

• internal/config/validation_schema.go (452 lines) - Core schema validation
• internal/config/validation_schema_test.go (696 lines) - Test suite
• internal/config/validation_schema_fetch_test.go (591 lines) - Fetch tests
• internal/config/validation_string_patterns_test.go - Pattern tests

Total Impact: 1,739 lines of schema-related code

Key APIs Used

1. Compiler API: NewCompiler(), compiler.Draft, AddResource(), Compile()
2. Validation API: schema.Validate(), *ValidationError type
3. Error Handling: Recursive error formatting with .Causes field

Usage Patterns

✅ Excellent Implementation:

• Schema caching with sync.Once for performance
• Remote schema fetching from GitHub
• Custom error formatter for user-friendly messages
• Comprehensive test coverage (21+ test cases)

⚠️ Workaround Required:

• fetchAndFixSchema() function applies regex fixes for Draft 7 limitations
• 80 lines of workaround code for negative lookahead patterns

Research Findings

Recent Updates

The module was last updated December 16, 2025 with validation fixes. The maintainer (santhosh-tekuri) is actively maintaining the project.

Version 6.0.2 Released

A major new version (v6) was released in May 2025 on the boon branch with significant improvements:

• Improved error handling with OutputError.String() method
• Performance optimizations for validation
• Better type validation support
• Custom vocabulary support
• API simplifications

Best Practices from Maintainer

The repository demonstrates:

• Multi-draft spec support for flexibility
• Detailed error messages with nested causes
• Full $ref resolution for complex schemas
• Extensible format validators
• Remote schema fetching capabilities

Improvement Opportunities

🏃 Quick Wins

1. Pin Schema Version for Build Reproducibility

Priority: HIGH | Effort: 5 minutes

Current Issue:
The schema URL uses the main branch which can change unexpectedly:

schemaURL = "https://raw.githubusercontent.com/github/gh-aw/main/docs/public/schemas/mcp-gateway-config.schema.json"

Solution:
The code already has a TODO comment about this (lines 32-40 in validation_schema.go). Pin to a specific version:

schemaURL = "https://raw.githubusercontent.com/github/gh-aw/v1.0.0/docs/public/schemas/mcp-gateway-config.schema.json"

Benefits:

• Predictable builds
• No surprise breaking changes
• Better debugging (know exact schema version)

2. Embed Schema with go:embed

Priority: MEDIUM | Effort: 15 minutes

Current Issue:
Network dependency with 10-second timeout on first validation.

Solution:

import _ "embed"

//go:embed mcp-gateway-config.schema.json
var embeddedSchema []byte

Benefits:

• Offline gateway operation
• Faster startup (no HTTP fetch)
• Zero network dependency
• Eliminates 10s timeout risk

3. Add Schema Validation Metrics

Priority: LOW | Effort: 10 minutes

Solution:

start := time.Now()
defer func() {
    logSchema.Printf("Schema validation took: %v", time.Since(start))
}()

Benefits:

• Performance monitoring
• Identify slow validations
• Track error patterns

✨ Feature Opportunities

Major Opportunity: Upgrade to v6.0.2

Priority: HIGH | Impact: Medium-High | Effort: 2-4 hours

Why Upgrade?

1. Eliminate Workarounds: The fetchAndFixSchema() function may no longer be needed - v6 might handle negative lookahead patterns natively
2. Better Error Messages: Enhanced OutputError.String() method
3. Performance Gains: Validation optimizations in v6
4. Modern API: Cleaner, more type-safe interfaces
5. Future-proof: Aligns with latest JSON Schema specifications

Migration Impact:

// Current (v5)
import "github.com/santhosh-tekuri/jsonschema/v5"

// Future (v6) - import path changes
import "github.com/santhosh-tekuri/jsonschema/v6"

Testing Required:

• All 1,739 lines of schema code
• 21+ validation test cases
• Verify workaround necessity
• Performance benchmarking

Challenges:

• Breaking API changes (major version)
• Nee...

Custom agent used: agentic-workflows
GitHub Agentic Workflows (gh-aw) - Create, debug, and upgrade AI-powered workflows with intelligent prompt routing

• Fixes [go-fan] Go Module Review: jsonschema #706

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR addresses build reproducibility concerns by pinning the JSON schema URL to a specific version (v0.41.1) instead of tracking the main branch, and adds performance metrics to help monitor validation operations.

Changes:

• Pinned schema URL from main branch to v0.41.1 for build reproducibility
• Added timing instrumentation for schema fetch, compilation, parsing, and validation operations
• Updated documentation comments with clear instructions for updating schema versions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.