SebastienMelki
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎Makefile‎
Lines changed: 3 additions & 1 deletion b/‎Makefile‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 1 addition & 0 deletions b/‎README.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/http-generation.md‎
Lines changed: 46 additions & 26 deletions b/‎docs/http-generation.md‎
Lines changed: 46 additions & 26 deletions
diff --git a/‎docs/validation.md‎
Lines changed: 84 additions & 10 deletions b/‎docs/validation.md‎
Lines changed: 84 additions & 10 deletions
diff --git a/‎examples/simple-api/Makefile‎
Lines changed: 0 additions & 1 deletion b/‎examples/simple-api/Makefile‎
Lines changed: 0 additions & 1 deletion
@@ -62,3 +62,6 @@ internal/generated/proto/
 
 # Generated sqlc files
 internal/modules/*/internal/infrastructure/persistence/sqlc/
+
+# Temporary test files
+*.generated
@@ -110,9 +110,11 @@ proto:
 	@protoc --go_out=. --go_opt=module=github.com/SebastienMelki/sebuf \
 		--go_opt=Msebuf/http/annotations.proto=github.com/SebastienMelki/sebuf/http \
 		--go_opt=Msebuf/http/headers.proto=github.com/SebastienMelki/sebuf/http \
+		--go_opt=Msebuf/http/errors.proto=github.com/SebastienMelki/sebuf/http \
 		--proto_path=. \
 		proto/sebuf/http/annotations.proto \
-		proto/sebuf/http/headers.proto
+		proto/sebuf/http/headers.proto \
+		proto/sebuf/http/errors.proto
 
 # Publish annotations to Buf Schema Registry
 .PHONY: publish
 
@@ -33,6 +33,7 @@ This starts a working HTTP API with JSON endpoints, OpenAPI docs, and helper fun
 - **Mock server generation** with realistic field examples for rapid prototyping
 - **Automatic request validation** using protovalidate with buf.validate annotations
 - **HTTP header validation** with type checking and format validation (UUID, email, datetime)
+- **Structured error responses** with field-level validation details in JSON or protobuf
 - **OpenAPI v3.1 docs** that stay in sync with your code, one file per service for better organization
 - **Helper functions** that eliminate protobuf boilerplate
 - **Zero runtime dependencies** - works with any Go HTTP framework
 
@@ -608,33 +608,39 @@ service UserService {
 
 ### Generated Validation Code
 
-The plugin generates header validation middleware that's automatically applied:
+The plugin generates header validation that returns structured errors:
 
 ```go
-// Generated middleware validates headers before processing requests
-func validateHeaders(requiredHeaders []HeaderConfig) func(http.Handler) http.Handler {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            // Validate each required header
-            for _, header := range requiredHeaders {
-                value := r.Header.Get(header.Name)
-                
-                // Check required headers
-                if header.Required && value == "" {
-                    http.Error(w, fmt.Sprintf("Missing required header: %s", header.Name), 400)
-                    return
-                }
-                
-                // Validate type and format
-                if err := validateHeaderValue(value, header.Type, header.Format); err != nil {
-                    http.Error(w, fmt.Sprintf("Invalid header %s: %v", header.Name, err), 400)
-                    return
-                }
-            }
-            
-            next.ServeHTTP(w, r)
-        })
+// Generated validation returns ValidationError with field-level violations
+func validateHeaders(r *http.Request, serviceHeaders, methodHeaders []*Header) *ValidationError {
+    var violations []*FieldViolation
+    allHeaders := mergeHeaders(serviceHeaders, methodHeaders)
+    
+    for _, header := range allHeaders {
+        value := r.Header.Get(header.Name)
+        
+        // Check required headers
+        if header.Required && value == "" {
+            violations = append(violations, &FieldViolation{
+                Field: header.Name,
+                Description: fmt.Sprintf("required header '%s' is missing", header.Name),
+            })
+            continue
+        }
+        
+        // Validate type and format
+        if err := validateHeaderValue(header, value); err != nil {
+            violations = append(violations, &FieldViolation{
+                Field: header.Name,
+                Description: fmt.Sprintf("header '%s' validation failed: %v", header.Name, err),
+            })
+        }
+    }
+    
+    if len(violations) > 0 {
+        return &ValidationError{Violations: violations}
     }
+    return nil
 }
 ```
 
@@ -697,15 +703,29 @@ curl -X POST http://localhost:8080/api/v1/users \
 curl -X POST http://localhost:8080/api/v1/users \
   -H "Content-Type: application/json" \
   -d '{"name": "John", "email": "john@example.com"}'
-# Response: 400 Bad Request - Missing required header: X-API-Key
+# Response: 400 Bad Request
+# Body:
+{
+  "violations": [{
+    "field": "X-API-Key",
+    "description": "required header 'X-API-Key' is missing"
+  }]
+}
 
 # Invalid header format (returns 400)
 curl -X POST http://localhost:8080/api/v1/users \
   -H "Content-Type: application/json" \
   -H "X-API-Key: not-a-uuid" \
   -H "X-Tenant-ID: 42" \
   -d '{"name": "John", "email": "john@example.com"}'
-# Response: 400 Bad Request - Invalid header X-API-Key: invalid UUID format
+# Response: 400 Bad Request
+# Body:
+{
+  "violations": [{
+    "field": "X-API-Key",
+    "description": "header 'X-API-Key' validation failed: invalid UUID format"
+  }]
+}
 ```
 
 ## Generated Code Structure
 
@@ -65,7 +65,8 @@ That's it! Both header and body validation happen automatically in your HTTP han
 - ✅ **Header type validation** - Support for string, integer, number, boolean, array types
 - ✅ **Header format validation** - Built-in validators for UUID, email, datetime formats
 - ✅ **Performance optimized** - Cached validator instances
-- ✅ **Clear error messages** - HTTP 400 with detailed validation errors
+- ✅ **Structured error responses** - JSON or protobuf ValidationError with field-level details
+- ✅ **Content-type aware** - Error format matches client's requested content type
 - ✅ **Fail-fast validation** - Headers validated before body for efficiency
 
 ## Request Body Validation Rules
@@ -291,48 +292,121 @@ service SecureAPI {
 
 ## Error Handling
 
-When validation fails, sebuf returns an HTTP 400 Bad Request with the validation error message. Headers are validated before the request body.
+When validation fails, sebuf returns an HTTP 400 Bad Request with a structured error response. The response format respects the client's `Content-Type` header, returning either JSON or protobuf. Headers are validated before the request body.
+
+### Structured Error Response Format
+
+Validation errors are returned as a `ValidationError` message containing field-level violations:
+
+```protobuf
+message ValidationError {
+  repeated FieldViolation violations = 1;
+}
+
+message FieldViolation {
+  string field = 1;       // Field that failed validation
+  string description = 2; // Description of the violation
+}
+```
 
 ### Header Validation Errors
 
 ```bash
 # Missing required header
-curl -X POST /api/users -d '{"name": "John"}'
+curl -X POST /api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John"}'
 # Returns: 400 Bad Request
-# Body: "Missing required header: X-API-Key"
+# Body: 
+{
+  "violations": [{
+    "field": "X-API-Key",
+    "description": "required header 'X-API-Key' is missing"
+  }]
+}
 
 # Invalid header format (UUID)
 curl -X POST /api/users \
+  -H "Content-Type: application/json" \
   -H "X-API-Key: not-a-uuid" \
   -d '{"name": "John"}'
 # Returns: 400 Bad Request
-# Body: "Invalid header X-API-Key: invalid UUID format"
+# Body:
+{
+  "violations": [{
+    "field": "X-API-Key",
+    "description": "header 'X-API-Key' validation failed: invalid UUID format"
+  }]
+}
 
 # Invalid header type (expecting integer)
 curl -X POST /api/users \
+  -H "Content-Type: application/json" \
   -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
   -H "X-Tenant-ID: abc" \
   -d '{"name": "John"}'
 # Returns: 400 Bad Request
-# Body: "Invalid header X-Tenant-ID: must be an integer"
+# Body:
+{
+  "violations": [{
+    "field": "X-Tenant-ID",
+    "description": "header 'X-Tenant-ID' validation failed: value is not a valid integer"
+  }]
+}
 ```
 
 ### Body Validation Errors
 
 ```bash
 # Invalid email
 curl -X POST /api/users \
+  -H "Content-Type: application/json" \
   -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
   -d '{"email": "invalid"}'
 # Returns: 400 Bad Request
-# Body: "validation error: field 'email' with value 'invalid' failed rule 'string.email'"
+# Body:
+{
+  "violations": [{
+    "field": "email",
+    "description": "value must be a valid email address"
+  }]
+}
 
-# Name too short  
+# Multiple validation failures
 curl -X POST /api/users \
+  -H "Content-Type: application/json" \
   -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
-  -d '{"name": "J"}'
+  -d '{"name": "J", "email": "invalid", "age": 200}'
 # Returns: 400 Bad Request
-# Body: "validation error: field 'name' with value 'J' failed rule 'string.min_len'"
+# Body:
+{
+  "violations": [
+    {
+      "field": "name",
+      "description": "value length must be at least 2 runes"
+    },
+    {
+      "field": "email",
+      "description": "value must be a valid email address"
+    },
+    {
+      "field": "age",
+      "description": "value must be less than or equal to 120"
+    }
+  ]
+}
+```
+
+### Binary Response Format
+
+When using protobuf content type, errors are returned as binary protobuf:
+
+```bash
+curl -X POST /api/users \
+  -H "Content-Type: application/x-protobuf" \
+  -H "X-API-Key: invalid" \
+  --data-binary @request.pb
+# Returns: 400 Bad Request with binary ValidationError protobuf
 ```
 
 ## Advanced Usage
 
@@ -40,7 +40,6 @@ clean:
 	@rm -f *.pb.go
 	@rm -f *_helpers.pb.go
 	@rm -f *_http*.pb.go
-	@rm -f *.yaml *.json
 	@echo "✅ Cleaned generated files"
 
 # Test the API endpoints