Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 2 — Organization Service

Validation

Reject malformed input before it ever reaches a service method — and give the slug format a rule precise enough to write a regex for.

14 min readHOA Backend Engineering CourseMaster

ShouldBindJSON Confirms Shape, Not Correctness

c.ShouldBindJSON already rejects a request body that isn't valid JSON or doesn't match CreateOrganizationRequest's field types. It does not reject an empty name, a slug containing uppercase letters or spaces, or a contact_email that isn't actually an email address — all of those are syntactically valid JSON strings. internal/validation closes that gap with a single shared *validator.Validate instance and one custom rule this platform actually needs: slug.

Terminal — services/organization

$go get github.com/go-playground/validator/v10@v10.22.1

$mkdir -p internal/validation

$touch internal/validation/validator.go

One Custom Rule, Not a General-Purpose Validation Framework

validator ships dozens of built-in tags (required, email, max, len) that cover almost everything this DTO needs. The only rule this platform actually invented is slug: lowercase letters and digits, hyphen-separated, no leading, trailing, or doubled hyphens — because a slug becomes part of a URL path and, later in this course, a Kubernetes-adjacent DNS-safe identifier, so both ends of that lifecycle need the same narrow shape enforced once, here.

Create services/organization/internal/validation/validator.go before adding the code

$mkdir -p services/organization/internal/validation && touch services/organization/internal/validation/validator.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/validation/validator.go

package validation

import (
	"regexp"

	"github.com/go-playground/validator/v10"
)

var slugPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)

// New builds a *validator.Validate with this platform's one custom rule
// registered. It is constructed once, in the composition root, and shared
// — validator.Validate caches struct reflection internally, so building a
// fresh instance per request would silently discard that cache every time.
func New() *validator.Validate {
	v := validator.New()
	_ = v.RegisterValidation("slug", func(fl validator.FieldLevel) bool {
		return slugPattern.MatchString(fl.Field().String())
	})
	return v
}

// FieldErrors flattens validator's *validator.InvalidValidationError /
// validator.ValidationErrors into the plain map[string]string shape
// apperr.InvalidInput expects, so a handler never has to import validator
// itself to report a failure.
func FieldErrors(err error) map[string]string {
	fieldErrs, ok := err.(validator.ValidationErrors)
	if !ok {
		return map[string]string{"body": err.Error()}
	}
	details := make(map[string]string, len(fieldErrs))
	for _, fe := range fieldErrs {
		details[fe.Field()] = fe.Tag()
	}
	return details
}

Wiring validate Tags Onto CreateOrganizationRequest

Create services/organization/internal/dto/organization.go before adding the code

$mkdir -p services/organization/internal/dto && touch services/organization/internal/dto/organization.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/dto/organization.go (modify — adds validate struct tags to the create request)

type CreateOrganizationRequest struct {
	Name               string `json:"name" validate:"required,min=2,max=200"`
	Slug               string `json:"slug" validate:"required,slug,max=100"`
	RegistrationNumber string `json:"registration_number" validate:"required,max=50"`
	ContactEmail       string `json:"contact_email" validate:"required,email"`
	ContactPhone       string `json:"contact_phone" validate:"omitempty,max=30"`
	AddressLine1       string `json:"address_line1" validate:"required,max=200"`
	AddressLine2       string `json:"address_line2" validate:"omitempty,max=200"`
	City               string `json:"city" validate:"required,max=100"`
	State              string `json:"state" validate:"required,max=100"`
	PostalCode         string `json:"postal_code" validate:"required,max=20"`
	Country            string `json:"country" validate:"required,len=3"`
}

// UpdateOrganizationRequest's pointer fields use omitempty so a nil field
// (an omitted key) is never validated at all — only a present, non-nil
// value is checked against the same rules as its create-request sibling.
type UpdateOrganizationRequest struct {
	Name         *string `json:"name" validate:"omitempty,min=2,max=200"`
	ContactEmail *string `json:"contact_email" validate:"omitempty,email"`
	ContactPhone *string `json:"contact_phone" validate:"omitempty,max=30"`
	AddressLine1 *string `json:"address_line1" validate:"omitempty,max=200"`
	AddressLine2 *string `json:"address_line2" validate:"omitempty,max=200"`
}

Country requires exactly 3 characters — an ISO 3166-1 alpha-3 code (USA, CAN, MEX) — rather than a free-text country name, because a fixed-width code is what every downstream integration in later phases (tax rules, mailing formats) will actually key off of.

The Handler Gains a Second Dependency, Not a Second Layer

Create services/organization/internal/handler/organization_handler.go before adding the code

$mkdir -p services/organization/internal/handler && touch services/organization/internal/handler/organization_handler.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/handler/organization_handler.go (modify — Create and Update now validate before calling the service)

 type OrganizationHandler struct {
    svc      *service.OrganizationService
	+	validate *validator.Validate
	 }

	-func NewOrganizationHandler(svc *service.OrganizationService) *OrganizationHandler {
	-	return &OrganizationHandler{svc: svc}
	+func NewOrganizationHandler(svc *service.OrganizationService, validate *validator.Validate) *OrganizationHandler {
	+	return &OrganizationHandler{svc: svc, validate: validate}
	 }

	 func (h *OrganizationHandler) Create(c *gin.Context) {
    // Existing JSON binding remains unchanged.
	+	if err := h.validate.Struct(req); err != nil {
	+		respondError(c, apperr.InvalidInput("validation failed", validation.FieldErrors(err)))
	+		return
	+	}
    // Existing service call and 201 response remain unchanged.
	 }

	 func (h *OrganizationHandler) Update(c *gin.Context) {
    // Existing id parsing and JSON binding remain unchanged.
	+	if err := h.validate.Struct(req); err != nil {
	+		respondError(c, apperr.InvalidInput("validation failed", validation.FieldErrors(err)))
	+		return
	+	}
    // Existing service call and 200 response remain unchanged.
	 }

Get, List, Suspend, and Archive are unchanged — they take no request body, so there is nothing for this validator to check. Only the two handler methods that bind a JSON body gain the second validate.Struct call.

Create services/organization/cmd/api/main.go before adding the code

$mkdir -p services/organization/cmd/api && touch services/organization/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/cmd/api/main.go (modify — the composition root constructs one shared validator)

	repo := repository.NewOrganizationPostgres(pool)
	svc := service.NewOrganizationService(repo)
	orgHandler := handler.NewOrganizationHandler(svc, validation.New())
	engine := router.New(orgHandler)

Only the handler construction line changes; everything above and below it in main is identical to the REST API Design lesson's version.

Why FieldErrors returns tag names, not full sentences

fe.Tag() returns the short rule name that failed — "required", "email", "slug" — not a prose sentence. A machine-readable code per field lets a future admin console highlight the exact offending input and choose its own localized message, instead of parsing an English sentence back apart to find out which rule failed.

Confirming the Custom slug Rule Actually Rejects What It Should

Terminal — services/organization

$go run ./cmd/api &

$curl -s -i -X POST http://localhost:8080/api/v1/organizations -d '{"name":"Bad Slug HOA","slug":"Bad Slug!","registration_number":"REG-200","contact_email":"not-an-email","address_line1":"1 Test St","city":"Austin","state":"TX","postal_code":"73301","country":"USA"}'

// Expect HTTP 422 with details containing both "Slug":"slug" and "ContactEmail":"email".

$kill %1

Applied exercise

Find a slug the regex wrongly accepts or wrongly rejects

12 minutes

Regexes are easy to get subtly wrong at their edges. Probe this one directly instead of trusting it by inspection.

Write a small Go program (or a quick REPL-style test) that checks slugPattern.MatchString against: "a", "a-b", "a--b", "-a", "a-", "123", "a_b".
Record which of these the current pattern accepts and which it rejects.
Explain which repeated group in the regex accepts "a-b" while rejecting "a--b", then add one edge case of your own that could falsify your explanation.

Deliverable

A short table of the seven test inputs, their pass/fail result, and one additional edge-case assertion.

Completion checks

The table correctly identifies that "a--b" is rejected because every repeated hyphen must be followed immediately by one or more lowercase alphanumeric characters.
The added edge case is executed against the regex rather than judged only by inspection.

Quiz & Practice

Question 1 / 1

Why does UpdateOrganizationRequest's validate tags use omitempty on every field, while CreateOrganizationRequest largely does not?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Course outline

01 · Phase 1 — Project Foundation16/16

02 · Phase 2 — Organization Service20/20

03 · Phase 3 — User Service10/10

04 · Phase 4 — Authentication Service10/10

05 · Phase 5 — API Gateway9/9

06 · Phase 6 — Flat Service6/6

07 · Phase 7 — Resident Service7/7

08 · Phase 8 — Maintenance Service7/7

09 · Phase 9 — Payment Service7/7

10 · Phase 10 — Complaint Service7/7

11 · Phase 11 — Notice Service7/7

12 · Phase 12 — Visitor Service6/6

13 · Phase 13 — Staff Service6/6

14 · Phase 14 — Notification Service7/7

15 · Phase 15 — Redis Integration6/6

16 · Phase 16 — Kafka Integration8/8

17 · Phase 17 — Observability7/7

18 · Phase 18 — Performance Engineering6/6

19 · Phase 19 — Production Deployment11/11

20 · Phase 20 — Production Readiness8/8

Stage 7 · Master

Phase 2 — Organization Service

Validation

Reject malformed input before it ever reaches a service method — and give the slug format a rule precise enough to write a regex for.

14 min readHOA Backend Engineering CourseMaster

ShouldBindJSON Confirms Shape, Not Correctness

Terminal — services/organization

$go get github.com/go-playground/validator/v10@v10.22.1

$mkdir -p internal/validation

$touch internal/validation/validator.go

One Custom Rule, Not a General-Purpose Validation Framework

Create services/organization/internal/validation/validator.go before adding the code

$mkdir -p services/organization/internal/validation && touch services/organization/internal/validation/validator.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/validation/validator.go

package validation

import (
	"regexp"

	"github.com/go-playground/validator/v10"
)

var slugPattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)

// New builds a *validator.Validate with this platform's one custom rule
// registered. It is constructed once, in the composition root, and shared
// — validator.Validate caches struct reflection internally, so building a
// fresh instance per request would silently discard that cache every time.
func New() *validator.Validate {
	v := validator.New()
	_ = v.RegisterValidation("slug", func(fl validator.FieldLevel) bool {
		return slugPattern.MatchString(fl.Field().String())
	})
	return v
}

// FieldErrors flattens validator's *validator.InvalidValidationError /
// validator.ValidationErrors into the plain map[string]string shape
// apperr.InvalidInput expects, so a handler never has to import validator
// itself to report a failure.
func FieldErrors(err error) map[string]string {
	fieldErrs, ok := err.(validator.ValidationErrors)
	if !ok {
		return map[string]string{"body": err.Error()}
	}
	details := make(map[string]string, len(fieldErrs))
	for _, fe := range fieldErrs {
		details[fe.Field()] = fe.Tag()
	}
	return details
}

Wiring validate Tags Onto CreateOrganizationRequest

Create services/organization/internal/dto/organization.go before adding the code

$mkdir -p services/organization/internal/dto && touch services/organization/internal/dto/organization.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/dto/organization.go (modify — adds validate struct tags to the create request)

type CreateOrganizationRequest struct {
	Name               string `json:"name" validate:"required,min=2,max=200"`
	Slug               string `json:"slug" validate:"required,slug,max=100"`
	RegistrationNumber string `json:"registration_number" validate:"required,max=50"`
	ContactEmail       string `json:"contact_email" validate:"required,email"`
	ContactPhone       string `json:"contact_phone" validate:"omitempty,max=30"`
	AddressLine1       string `json:"address_line1" validate:"required,max=200"`
	AddressLine2       string `json:"address_line2" validate:"omitempty,max=200"`
	City               string `json:"city" validate:"required,max=100"`
	State              string `json:"state" validate:"required,max=100"`
	PostalCode         string `json:"postal_code" validate:"required,max=20"`
	Country            string `json:"country" validate:"required,len=3"`
}

// UpdateOrganizationRequest's pointer fields use omitempty so a nil field
// (an omitted key) is never validated at all — only a present, non-nil
// value is checked against the same rules as its create-request sibling.
type UpdateOrganizationRequest struct {
	Name         *string `json:"name" validate:"omitempty,min=2,max=200"`
	ContactEmail *string `json:"contact_email" validate:"omitempty,email"`
	ContactPhone *string `json:"contact_phone" validate:"omitempty,max=30"`
	AddressLine1 *string `json:"address_line1" validate:"omitempty,max=200"`
	AddressLine2 *string `json:"address_line2" validate:"omitempty,max=200"`
}

The Handler Gains a Second Dependency, Not a Second Layer

Create services/organization/internal/handler/organization_handler.go before adding the code

$mkdir -p services/organization/internal/handler && touch services/organization/internal/handler/organization_handler.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/internal/handler/organization_handler.go (modify — Create and Update now validate before calling the service)

 type OrganizationHandler struct {
    svc      *service.OrganizationService
	+	validate *validator.Validate
	 }

	-func NewOrganizationHandler(svc *service.OrganizationService) *OrganizationHandler {
	-	return &OrganizationHandler{svc: svc}
	+func NewOrganizationHandler(svc *service.OrganizationService, validate *validator.Validate) *OrganizationHandler {
	+	return &OrganizationHandler{svc: svc, validate: validate}
	 }

	 func (h *OrganizationHandler) Create(c *gin.Context) {
    // Existing JSON binding remains unchanged.
	+	if err := h.validate.Struct(req); err != nil {
	+		respondError(c, apperr.InvalidInput("validation failed", validation.FieldErrors(err)))
	+		return
	+	}
    // Existing service call and 201 response remain unchanged.
	 }

	 func (h *OrganizationHandler) Update(c *gin.Context) {
    // Existing id parsing and JSON binding remain unchanged.
	+	if err := h.validate.Struct(req); err != nil {
	+		respondError(c, apperr.InvalidInput("validation failed", validation.FieldErrors(err)))
	+		return
	+	}
    // Existing service call and 200 response remain unchanged.
	 }

Create services/organization/cmd/api/main.go before adding the code

$mkdir -p services/organization/cmd/api && touch services/organization/cmd/api/main.go

// touch preserves an existing file, so the same command is safe when revisiting the lesson.

services/organization/cmd/api/main.go (modify — the composition root constructs one shared validator)

	repo := repository.NewOrganizationPostgres(pool)
	svc := service.NewOrganizationService(repo)
	orgHandler := handler.NewOrganizationHandler(svc, validation.New())
	engine := router.New(orgHandler)

Only the handler construction line changes; everything above and below it in main is identical to the REST API Design lesson's version.

Why FieldErrors returns tag names, not full sentences

Confirming the Custom slug Rule Actually Rejects What It Should

Terminal — services/organization

$go run ./cmd/api &

// Expect HTTP 422 with details containing both "Slug":"slug" and "ContactEmail":"email".

$kill %1

Applied exercise

Find a slug the regex wrongly accepts or wrongly rejects

12 minutes

Regexes are easy to get subtly wrong at their edges. Probe this one directly instead of trusting it by inspection.

Write a small Go program (or a quick REPL-style test) that checks slugPattern.MatchString against: "a", "a-b", "a--b", "-a", "a-", "123", "a_b".
Record which of these the current pattern accepts and which it rejects.
Explain which repeated group in the regex accepts "a-b" while rejecting "a--b", then add one edge case of your own that could falsify your explanation.

Deliverable

A short table of the seven test inputs, their pass/fail result, and one additional edge-case assertion.

Completion checks

The table correctly identifies that "a--b" is rejected because every repeated hyphen must be followed immediately by one or more lowercase alphanumeric characters.
The added edge case is executed against the regex rather than judged only by inspection.

Quiz & Practice

Question 1 / 1

Why does UpdateOrganizationRequest's validate tags use omitempty on every field, while CreateOrganizationRequest largely does not?

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.