Validation Showcase Example

This example demonstrates comprehensive request validation using buf.validate (protovalidate), showcasing all validation patterns available in sebuf.

Features Demonstrated#

String Validation#

Constraint	Description	Example
`min_len/max_len`	Length constraints	`string name = 1 [(buf.validate.field).string = { min_len: 2, max_len: 100 }]`
`email`	Email format	`string email = 1 [(buf.validate.field).string.email = true]`
`uuid`	UUID format	`string id = 1 [(buf.validate.field).string.uuid = true]`
`pattern`	Regex pattern	`string phone = 1 [(buf.validate.field).string.pattern = "^\\+[1-9]\\d{6,14}$"]`
`in`	Enum values	`string country = 1 [(buf.validate.field).string = { in: ["US", "CA", "MX"] }]`

Numeric Validation#

Constraint	Description	Example
`gte/lte`	Inclusive range	`int32 quantity = 1 [(buf.validate.field).int32 = { gte: 1, lte: 100 }]`
`gt/lt`	Exclusive range	`double price = 1 [(buf.validate.field).double = { gt: 0, lte: 10000 }]`

Array/Repeated Validation#

Constraint	Description	Example
`min_items/max_items`	Size constraints	`repeated Item items = 1 [(buf.validate.field).repeated = { min_items: 1, max_items: 50 }]`
`unique`	No duplicates	`repeated string codes = 1 [(buf.validate.field).repeated = { unique: true }]`
`items`	Element validation	`repeated string emails = 1 [(buf.validate.field).repeated = { items: { string: { email: true } } }]`

Map Validation#

Constraint	Description	Example
`max_pairs`	Size limit	`map<string, string> meta = 1 [(buf.validate.field).map = { max_pairs: 20 }]`
`keys`	Key validation	`map<string, string> opts = 1 [(buf.validate.field).map = { keys: { string: { pattern: "^[a-z_]+$" } } }]`
`values`	Value validation	`map<string, string> opts = 1 [(buf.validate.field).map = { values: { string: { max_len: 100 } } }]`

Nested Message Validation#

Constraint	Description	Example
`required`	Required nested message	`Address shipping = 1 [(buf.validate.field).required = true]`

Quick Start#

# Generate code and run the server
make demo
 
# Test valid requests
make test
 
# Test validation errors (expect HTTP 400)
make test-validation

API Endpoints#

Method	Endpoint	Description
POST	`/api/v1/orders`	Create order with full validation
GET	`/api/v1/orders/{order_id}`	Get order by UUID
POST	`/api/v1/validate/address`	Validate shipping address
POST	`/api/v1/validate/coupon`	Validate coupon code

Example: Create Order#

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "contact": {
      "email": "john.doe@example.com",
      "phone": "+14155551234"
    },
    "shipping_address": {
      "street": "123 Main Street, Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    },
    "items": [{
      "product_id": "123e4567-e89b-12d3-a456-426614174000",
      "product_name": "Wireless Headphones",
      "sku": "SKU-ABC123DEF",
      "quantity": 2,
      "unit_price": 99.99,
      "discount_percent": 10.0,
      "options": {"color": "blue", "size": "large"}
    }],
    "coupon_codes": ["SAVE20"],
    "payment_method": 1
  }'

Validation Error Examples#

Invalid Email Format#

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{"contact": {"email": "not-an-email"}, ...}'

Response (HTTP 400):

{
  "violations": [{
    "field": "contact.email",
    "description": "value must be a valid email address"
  }]
}

Invalid State Code (Pattern)#

curl -X POST http://localhost:8080/api/v1/validate/address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{"address": {"state": "California", ...}}'

Response (HTTP 400):

{
  "violations": [{
    "field": "address.state",
    "description": "value does not match pattern: ^[A-Z]{2}$"
  }]
}

Quantity Out of Range#

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{"items": [{"quantity": 500, ...}], ...}'

Response (HTTP 400):

{
  "violations": [{
    "field": "items[0].quantity",
    "description": "value must be less than or equal to 100"
  }]
}

Empty Items Array#

curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{"items": [], ...}'

Response (HTTP 400):

{
  "violations": [{
    "field": "items",
    "description": "value must contain at least 1 item(s)"
  }]
}

Generated Files#

After running make generate:

api/
  proto/
    models/
      order.pb.go              # Order, Address, OrderItem messages
    services/
      order_service.pb.go            # Service interface
      order_service_http.pb.go       # HTTP handler registration
      order_service_http_binding.pb.go  # Request binding + validation
      order_service_http_config.pb.go   # Server options
      order_service_http_mock.pb.go     # Mock implementation
docs/
  OrderService.openapi.yaml    # OpenAPI 3.1 with validation constraints
  OrderService.openapi.json    # OpenAPI 3.1 (JSON format)

Key Concepts#

Automatic Validation#

All validation happens automatically in the generated BindingMiddleware. You don't need to write any validation code - just define the rules in your proto files.

Validation Error Format#

Validation errors return HTTP 400 with a structured response containing:

violations[]: Array of field violations
- field: Path to the invalid field (e.g., items[0].quantity)
- description: Human-readable error message

OpenAPI Integration#

Validation constraints are automatically reflected in the generated OpenAPI specs:

minLength/maxLength for string constraints
minimum/maximum for numeric constraints
minItems/maxItems for array constraints
pattern for regex constraints
enum for in constraints