NLG Form

A type-safe validation framework for Go applications.

Use form to validate JSON requests, API payloads, and application input through reusable schemas, typed fields, and composable validation rules.

---

Requirements

This package requires Go 1.22 or newer.

It is designed for modern Go projects and may use language and standard library features introduced in recent Go versions.

• Go: 1.22 or newer
• Dependencies: Standard library only

Installation

Add the package to your project using go get:

go get github.com/netlifeguru/form

Import the package into your application:

import (
	"github.com/netlifeguru/form"
	"github.com/netlifeguru/form/rules"
)

Additional optional modules are available through subpackages:

import (
	"github.com/netlifeguru/form/conditional"
	"github.com/netlifeguru/form/httpform"
	"github.com/netlifeguru/form/optional"
)

The package is designed to integrate naturally with Go structs, net/http handlers, JSON request processing, and reusable application validation workflows.

Once installed, continue with the Quick Start guide to create your first validation schema and validate incoming request data.

Getting Started

The example below demonstrates a complete validation workflow using:

• HTTP request binding
• Typed validation schemas
• Reusable validation rules
• JSON request validation
• Structured request processing

The incoming request is a standard HTTP POST request with a JSON payload:

{
  "name": "abcdefd",
  "age": 10
}

The validation flow consists of:

1. Defining a request structure
2. Creating reusable typed form fields
3. Building validation rules
4. Binding and validating the HTTP request
5. Returning structured JSON responses

---

Create the Request Schema

The schema defines reusable typed fields and validation rules for the incoming request.

Schemas are typically defined through functions instead of global variables to keep validation definitions immutable and isolated between application components.

package main

import (
	"github.com/netlifeguru/form"
	"github.com/netlifeguru/form/rules"
)

type PostRequest struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

func PostSchema() form.Schema[PostRequest] {
	var PostForm = struct {
		Name form.StringField[PostRequest]
		Age  form.IntField[PostRequest]
	}{
		Name: form.Str[PostRequest]("name", func(r *PostRequest) string {
			return r.Name
		}),
		Age: form.Int[PostRequest]("age", func(r *PostRequest) int {
			return r.Age
		}),
	}

	var NameSchema = form.Schema[PostRequest]{
		rules.Required(PostForm.Name),
		rules.MinLen(PostForm.Name, 5),
	}

	var AgeSchema = form.Schema[PostRequest]{
		rules.RequiredInt(PostForm.Age),
		rules.Min(PostForm.Age, 8),
	}

	return form.Rules(
		NameSchema,
		AgeSchema,
	)
}

---

Create the HTTP Server

The HTTP handler binds the incoming JSON request into the PostRequest structure and validates it using the schema.

package main

import (
	"encoding/json"
	"fmt"
	"log/slog"
	"net/http"
	"os"

	"github.com/netlifeguru/form"
	"github.com/netlifeguru/form/httpform"
	"github.com/netlifeguru/router"
)

func main() {
	r := router.New()

	r.HandleFunc("/", "POST", func(w http.ResponseWriter, r *http.Request, ctx *router.Context) {
		var in PostRequest

		if !httpform.BindAndValidate(w, r, &in, PostSchema(), 1<<20) {
			fmt.Println("form validation failed")
			return
		}

		fmt.Println("request received:", in)

		w.Header().Set("Content-Type", "application/json")

		_ = json.NewEncoder(w).Encode(map[string]any{
			"message": "request received",
			"data":    in,
		})
	})

	form.SendTestPost(":8080/", map[string]any{
		"name": "abcdefd",
		"age":  10,
	})

	if err := r.ListenAndServe(8080); err != nil {
		slog.Error("failed to start server", "error", err)
		os.Exit(1)
	}
}

Note

The example uses the helper method:

form.SendTestPost(":8080/", map[string]any{
    "name": "abcdefd",
    "age":  10,
})

to automatically send a test HTTP POST request to the local server after startup.

This helper exists only to make the example self-contained and immediately runnable without requiring external tools such as curl or Postman.

---

Run the Application

Start the application:

go run .

The server starts on:

http://localhost:8080

---

Example Response

Successful validation returns a structured JSON response:

{
  "message": "request received",
  "data": {
    "name": "abcdefd",
    "age": 10
  }
}

If validation fails, the package automatically generates structured validation error responses through the httpform module.

Continue with the next sections to learn about validation rules, optional fields, conditional validation, custom error messages, schema composition, and advanced HTTP request processing.

---

Documentation

Full package documentation, guides, and examples are available at:

https://netlife.guru/docs/go/form

API reference is also available on pkg.go.dev:

https://pkg.go.dev/github.com/netlifeguru/form

---

Notes

• Review package-specific concurrency behavior before using it in highly parallel workloads.
• Check performance characteristics when using this package in latency-sensitive paths.
• See the package documentation and examples for limitations and recommended usage patterns.

---

Versioning

This project follows Semantic Versioning.
See CHANGELOG.md for release history and breaking changes.

---

Contributing

Community contributions, feedback, and improvements are welcome.

Please read CONTRIBUTING.md before submitting pull requests or opening issues.

---

Code of Conduct

This project follows a Code of Conduct.

Please read CODE_OF_CONDUCT.md before contributing or participating in discussions.

---

Author

Created and maintained by NetLife Guru s.r.o.

• Documentation: https://netlife.guru/docs/go/form
• GitHub: https://github.com/netlifeguru
• Contact: info@netlife.guru

---

License

MIT License. See LICENSE.