feat: add document-scoped format validators to prevent global state pollution

Add support for per-document format validators that are scoped to individual
OpenAPI specs instead of being shared globally. This solves the problem where
multiple specs in the same application cannot have different validation rules
for the same format name.

Problem:
DefineStringFormatValidator() uses global maps, causing issues when:
- Multiple OpenAPI specs are loaded in the same application
- Different specs need different validation logic for the same format name
- One spec's validator registration overwrites another's globally

Solution:
- Add format validator maps to openapi3.T (document-level storage)
- Add SetStringFormatValidator(), SetNumberFormatValidator(), and
  SetIntegerFormatValidator() methods to openapi3.T
- Add ValidateSchemaJSON() convenience method that automatically applies
  the document's validators
- Update schema validation logic to check: per-validation validators →
  document-scoped validators → global validators

Usage:
  specA := loader.LoadFromFile("spec-a.yaml")
  specA.SetStringFormatValidator("custom-id", validatorA)

  specB := loader.LoadFromFile("spec-b.yaml")
  specB.SetStringFormatValidator("custom-id", validatorB)

  // Each spec uses its own validators - no conflicts!
  err := specA.ValidateSchemaJSON(schemaA, value)
  err := specB.ValidateSchemaJSON(schemaB, value)

Changes:
- openapi3/openapi3.go: Add validator fields and methods to T
- openapi3/schema_validation_settings.go: Add per-validation validator options
- openapi3/schema.go: Update validation logic to check all validator sources
- openapi3/schema_formats_test.go: Add comprehensive tests

This change is fully backwards compatible. Existing code using global
validators continues to work unchanged.

Author: the-corp-mark

openapi3/openapi3.go

@@ -26,6 +26,12 @@ type T struct {
 
 	visited visitedComponent
 	url     *url.URL
+
+	// Document-scoped format validators
+	// These validators are automatically used by all schemas in this document
+	stringFormats  map[string]StringFormatValidator
+	numberFormats  map[string]NumberFormatValidator
+	integerFormats map[string]IntegerFormatValidator
 }
 
 var _ jsonpointer.JSONPointable = (*T)(nil)
@@ -137,6 +143,64 @@ func (doc *T) AddServers(servers ...*Server) {
 	doc.Servers = append(doc.Servers, servers...)
 }
 
+// SetStringFormatValidators sets document-scoped string format validators.
+// These validators are automatically used by all schemas in this document.
+func (doc *T) SetStringFormatValidators(validators map[string]StringFormatValidator) {
+	doc.stringFormats = validators
+}
+
+// SetStringFormatValidator sets a single document-scoped string format validator.
+func (doc *T) SetStringFormatValidator(name string, validator StringFormatValidator) {
+	if doc.stringFormats == nil {
+		doc.stringFormats = make(map[string]StringFormatValidator)
+	}
+	doc.stringFormats[name] = validator
+}
+
+// SetNumberFormatValidators sets document-scoped number format validators.
+// These validators are automatically used by all schemas in this document.
+func (doc *T) SetNumberFormatValidators(validators map[string]NumberFormatValidator) {
+	doc.numberFormats = validators
+}
+
+// SetNumberFormatValidator sets a single document-scoped number format validator.
+func (doc *T) SetNumberFormatValidator(name string, validator NumberFormatValidator) {
+	if doc.numberFormats == nil {
+		doc.numberFormats = make(map[string]NumberFormatValidator)
+	}
+	doc.numberFormats[name] = validator
+}
+
+// SetIntegerFormatValidators sets document-scoped integer format validators.
+// These validators are automatically used by all schemas in this document.
+func (doc *T) SetIntegerFormatValidators(validators map[string]IntegerFormatValidator) {
+	doc.integerFormats = validators
+}
+
+// SetIntegerFormatValidator sets a single document-scoped integer format validator.
+func (doc *T) SetIntegerFormatValidator(name string, validator IntegerFormatValidator) {
+	if doc.integerFormats == nil {
+		doc.integerFormats = make(map[string]IntegerFormatValidator)
+	}
+	doc.integerFormats[name] = validator
+}
+
+// GetSchemaValidationOptions returns SchemaValidationOptions that include
+// this document's format validators. Use this when validating schemas from this document.
+func (doc *T) GetSchemaValidationOptions() []SchemaValidationOption {
+	var opts []SchemaValidationOption
+	if doc.stringFormats != nil {
+		opts = append(opts, WithStringFormatValidators(doc.stringFormats))
+	}
+	if doc.numberFormats != nil {
+		opts = append(opts, WithNumberFormatValidators(doc.numberFormats))
+	}
+	if doc.integerFormats != nil {
+		opts = append(opts, WithIntegerFormatValidators(doc.integerFormats))
+	}
+	return opts
+}
+
 // Validate returns an error if T does not comply with the OpenAPI spec.
 // Validations Options can be provided to modify the validation behavior.
 func (doc *T) Validate(ctx context.Context, opts ...ValidationOption) error {
@@ -203,3 +267,11 @@ func (doc *T) Validate(ctx context.Context, opts ...ValidationOption) error {
 
 	return validateExtensions(ctx, doc.Extensions)
 }
+
+// ValidateSchemaJSON validates data against a schema using this document's format validators.
+// This is a convenience method that automatically applies the document's format validators.
+func (doc *T) ValidateSchemaJSON(schema *Schema, value any, opts ...SchemaValidationOption) error {
+	// Combine document's validators with any additional options
+	allOpts := append(doc.GetSchemaValidationOptions(), opts...)
+	return schema.VisitJSON(value, allOpts...)
+}

openapi3/schema.go

@@ -1527,7 +1527,12 @@ func (schema *Schema) visitJSONNumber(settings *schemaValidationSettings, value
 	format := schema.Format
 	if format != "" {
 		if requireInteger {
-			if f, ok := SchemaIntegerFormats[format]; ok {
+			// Check per-validation validators first, then fall back to global
+			f, ok := settings.integerFormats[format]
+			if !ok {
+				f, ok = SchemaIntegerFormats[format]
+			}
+			if ok {
 				if err := f.Validate(int64(value)); err != nil {
 					var reason string
 					schemaErr := &SchemaError{}
@@ -1541,7 +1546,12 @@ func (schema *Schema) visitJSONNumber(settings *schemaValidationSettings, value
 				}
 			}
 		} else {
-			if f, ok := SchemaNumberFormats[format]; ok {
+			// Check per-validation validators first, then fall back to global
+			f, ok := settings.numberFormats[format]
+			if !ok {
+				f, ok = SchemaNumberFormats[format]
+			}
+			if ok {
 				if err := f.Validate(value); err != nil {
 					var reason string
 					schemaErr := &SchemaError{}
@@ -1767,7 +1777,12 @@ func (schema *Schema) visitJSONString(settings *schemaValidationSettings, value
 	var formatStrErr string
 	var formatErr error
 	if format := schema.Format; format != "" {
-		if f, ok := SchemaStringFormats[format]; ok {
+		// Check per-validation validators first, then fall back to global
+		f, ok := settings.stringFormats[format]
+		if !ok {
+			f, ok = SchemaStringFormats[format]
+		}
+		if ok {
 			if err := f.Validate(value); err != nil {
 				var reason string
 				schemaErr := &SchemaError{}