checks_implementation_guide

GoZod Checks Implementation Guide

📋 Overview

This document provides implementation guidelines for GoZod validation checks based on the current architecture. All checks follow a unified factory function pattern that directly creates core.ZodCheckInternals instances with optional JSON Schema support.

🎯 Core Design Principles

1. Factory Function Pattern

• All check functions return core.ZodCheck interface
• Direct creation of core.ZodCheckInternals instances
• No wrapper types or unnecessary abstractions

2. JSON Schema Integration

• OnAttach callbacks for metadata generation
• Automatic constraint merging for compatible properties
• Type-appropriate attribute mapping

3. Validation Reuse

• Leverage pkg/validate package for actual validation logic
• Avoid duplicating validation implementations
• Focus on error handling and schema generation

🏗️ Current Architecture

Core Types (from core package)

// ZodCheck interface - implemented by ZodCheckInternals
type ZodCheck interface {
    GetZod() *ZodCheckInternals
}

// ZodCheckInternals - the main check implementation
type ZodCheckInternals struct {
    Def      *ZodCheckDef                     // Check definition
    Check    func(payload *ParsePayload)      // Validation function  
    OnAttach []func(any)                     // JSON Schema callbacks
    When     func(payload *ParsePayload) bool // Conditional execution
}

// ZodCheckDef - check metadata
type ZodCheckDef struct {
    Check  string                // Check type identifier
    Params map[string]any        // Check parameters
    Error  *ZodErrorMap         // Custom error mapping
}

Helper Functions (from internal/checks/checks.go)

// normalizeParams - standardize string parameters to error maps
func normalizeParams(def *ZodCheckDef, params []string)

// setBagProperty - set JSON Schema property
func setBagProperty(schema any, key string, value any)

// mergeConstraint - merge constraints with conflict resolution
func mergeConstraint(schema any, key string, value any, merge func(old, new any) any)

// mergeMinimumConstraint/mergeMaximumConstraint - boundary constraint merging
func mergeMinimumConstraint(schema any, value any, inclusive bool)
func mergeMaximumConstraint(schema any, value any, inclusive bool)