validation

To customize how Rule are evaluated use PropertyRules.Cascade. Use CascadeModeStop to stop validation after the first error. If you wish to revert to the default behavior, use CascadeModeContinue.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

func main() {
	alwaysFailingRule := validation.NewSingleRule(func(string) error {
		return fmt.Errorf("always fails")
	})

	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Cascade(validation.CascadeModeStop).
			Rules(validation.NotEqualTo("Jerry")).
			Rules(alwaysFailingRule),
	).WithName("Teacher")

	for _, name := range []string{"Tom", "Jerry"} {
		teacher := Teacher{Name: name}
		err := v.Validate(teacher)
		if err != nil {
			fmt.Println(err)
		}
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'name' with value 'Tom':
    - always fails
Validation for Teacher has failed for the following properties:
  - 'name' with value 'Jerry':
    - should be not equal to 'Jerry'

So far we've defined validation rules for simple, top-level properties. What If we want to define validation rules for nested properties? We can use PropertyRules.Include to include another Validator in our PropertyRules.

Let's extend our [Teacher] struct to include a nested [University] property. [University] in of itself is another struct with its own validation rules.

Notice how the nested property path is automatically built for you, each segment separated by a dot.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	universityValidation := validation.New[University](
		validation.For(func(u University) string { return u.Address }).
			WithName("address").
			Required(),
	)
	teacherValidation := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Rules(validation.EqualTo("Tom")),
		validation.For(func(t Teacher) University { return t.University }).
			WithName("university").
			Include(universityValidation),
	).WithName("Teacher")

	teacher := Teacher{
		Name: "Jerry",
		Age:  51 * year,
		University: University{
			Name:    "Poznan University of Technology",
			Address: "",
		},
	}

	err := teacherValidation.Validate(teacher)
	if err != nil {
		fmt.Println(err)
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'name' with value 'Jerry':
    - should be equal to 'Tom'
  - 'university.address':
    - property is required but was empty

While ForPointer will by default omit validation for nil pointers, it might be useful to have a similar behavior for optional properties which are direct values. PropertyRules.OmitEmpty will do the trick.

NOTE: PropertyRules.OmitEmpty will have no effect on pointers handled by ForPointer, as they already behave in the same way.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	alwaysFailingRule := validation.NewSingleRule(func(string) error {
		return fmt.Errorf("always fails")
	})

	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			OmitEmpty().
			Rules(alwaysFailingRule),
		validation.ForPointer(func(t Teacher) *string { return t.MiddleName }).
			WithName("middleName").
			Rules(alwaysFailingRule),
	).WithName("Teacher")

	teacher := Teacher{
		Name:       "",
		Age:        51 * year,
		MiddleName: nil,
	}

	err := v.Validate(teacher)
	if err == nil {
		fmt.Println("no error! we skipped 'name' validation and 'middleName' is implicitly skipped")
	}

}

Output:

no error! we skipped 'name' validation and 'middleName' is implicitly skipped

By default, when PropertyRules is constructed using ForPointer it will skip validation of the property if the pointer is nil. To enforce a value is set for pointer use PropertyRules.Required.

You may ask yourself why not just use validation.Required rule instead? If we were to do that, we'd be forced to operate on pointer in all of our rules. Other than checking if the pointer is nil, there aren't any rules which would benefit from working on the pointer instead of the underlying value.

If you want to also make sure the underlying value is filled, i.e. it's not a zero value, you can also use validation.Required rule on top of PropertyRules.Required.

PropertyRules.Required when used with For constructor, will ensure the property does not contain a zero value.

NOTE: PropertyRules.Required is introducing a short circuit. If the assertion fails, validation will stop and return validation.ErrorCodeRequired. None of the rules you've defined would be evaluated.

NOTE: Placement of PropertyRules.Required does not matter, it's not evaluated in a sequential loop, unlike standard Rule. However, we recommend you always place it below PropertyRules.WithName to make your rules more readable.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	alwaysFailingRule := validation.NewSingleRule(func(string) error {
		return fmt.Errorf("always fails")
	})

	v := validation.New[Teacher](
		validation.ForPointer(func(t Teacher) *string { return t.MiddleName }).
			WithName("middleName").
			Required().
			Rules(alwaysFailingRule),
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Required().
			Rules(alwaysFailingRule),
	).WithName("Teacher")

	teacher := Teacher{
		Name:       "",
		Age:        51 * year,
		MiddleName: nil,
	}

	err := v.Validate(teacher)
	if err != nil {
		fmt.Println(err)
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'middleName':
    - property is required but was empty
  - 'name':
    - property is required but was empty

To only run property validation on condition, use PropertyRules.When. Predicates set through PropertyRules.When are evaluated in the order they are provided. If any predicate is not met, validation rules are not evaluated for the whole PropertyRules.

It's recommended to define PropertyRules.When before PropertyRules.Rules declaration.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			When(func(t Teacher) bool { return t.Name == "Jerry" }).
			Rules(validation.NotEqualTo("Jerry")),
	).WithName("Teacher")

	for _, name := range []string{"Tom", "Jerry", "Mickey"} {
		teacher := Teacher{Name: name}
		err := v.Validate(teacher)
		if err != nil {
			fmt.Println(err)
		}
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'name' with value 'Jerry':
    - should be not equal to 'Jerry'

So far we've been using a very simple PropertyRules instance:

validation.For(func(t Teacher) string { return t.Name }).
	Rules(validation.NewSingleRule(func(name string) error { return fmt.Errorf("always fails") }))

The error message returned by this property rule does not tell us which property is failing. Let's change that by adding property name using PropertyRules.WithName.

We can also change the Rule to be something more real. Validation package comes with a number of predefined Rule, we'll use EqualTo which accepts a single argument, value to compare with.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Rules(validation.EqualTo("Tom")),
	).WithName("Teacher")

	teacher := Teacher{
		Name: "Jake",
		Age:  51 * year,
	}

	err := v.Validate(teacher)
	if err != nil {
		fmt.Println(err)
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'name' with value 'Jake':
    - should be equal to 'Tom'

You can use SingleRule.WithDetails to add additional details to the error message. This allows you to extend existing rules by adding your use case context. Let's give a regex validation some more clarity.

package main

import (
	"fmt"
	"regexp"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Rules(validation.StringMatchRegexp(regexp.MustCompile("^(Tom|Jerry)$")).
				WithDetails("Teacher can be either Tom or Jerry :)")),
	).WithName("Teacher")

	teacher := Teacher{
		Name: "Jake",
		Age:  51 * year,
	}

	err := v.Validate(teacher)
	if err != nil {
		fmt.Println(err)
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - 'name' with value 'Jake':
    - string must match regular expression: '^(Tom|Jerry)$'; Teacher can be either Tom or Jerry :)

When testing, it can be tedious to always rely on error messages as these can change over time. Enter ErrorCode, which is a simple string type alias used to ease testing, but also potentially allow third parties to integrate with your validation results. Use SingleRule.WithErrorCode to associate ErrorCode with a SingleRule. Notice that our modified version of StringMatchRegexp will now return a new ErrorCode. Predefined rules have ErrorCode already associated with them. To view the list of predefined ErrorCode checkout error_codes.go file.

package main

import (
	"fmt"
	"regexp"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			WithName("name").
			Rules(validation.StringMatchRegexp(regexp.MustCompile("^(Tom|Jerry)$")).
				WithDetails("Teacher can be either Tom or Jerry :)").
				WithErrorCode("custom_code")),
	).WithName("Teacher")

	teacher := Teacher{
		Name: "Jake",
		Age:  51 * year,
	}

	err := v.Validate(teacher)
	if err != nil {
		propertyErrors := err.Errors
		ruleErrors := propertyErrors[0].Errors
		fmt.Println(ruleErrors[0].Code)
	}

}

Output:

custom_code

Validator rules can be evaluated on condition, to specify the predicate use Validator.When function.

In this example, validation for [Teacher] instance will only be evaluated if the [Age] property is less than 50 years.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

const year = 24 * 365 * time.Hour

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			Rules(validation.NewSingleRule(func(name string) error { return fmt.Errorf("always fails") })),
	).
		When(func(t Teacher) bool { return t.Age < (50 * year) })

	// Prepare teachers.
	teacherTom := Teacher{
		Name: "Tom",
		Age:  51 * year,
	}
	teacherJerry := Teacher{
		Name: "Jerry",
		Age:  30 * year,
	}

	// Run validation.
	err := v.Validate(teacherTom)
	if err != nil {
		fmt.Println(err.WithName("Tom"))
	}
	err = v.Validate(teacherJerry)
	if err != nil {
		fmt.Println(err.WithName("Jerry"))
	}

}

Output:

Validation for Jerry has failed for the following properties:
  - always fails

To associate Validator with an entity name use Validator.WithName function. When any of the rules fails, the error will contain the entity name you've provided.

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			Rules(validation.NewSingleRule(func(name string) error { return fmt.Errorf("always fails") })),
	).WithName("Teacher")

	err := v.Validate(Teacher{})
	if err != nil {
		fmt.Println(err)
	}

}

Output:

Validation for Teacher has failed for the following properties:
  - always fails

You can also add Validator name during runtime, by calling ValidatorError.WithName function on the returned error.

NOTE: We left the previous "Teacher" name assignment, to demonstrate that the ValidatorError.WithName function call will shadow it.

NOTE: This would also work:

err := v.WithName("Jake").Validate(Teacher{})

Validation package, aside from errors handling, tries to follow immutability principle. Calling any function on Validator will not change its previous declaration (unless you assign it back to 'v').

package main

import (
	"fmt"
	"time"

	"github.com/nobl9/nobl9-go/internal/validation"
)

type Teacher struct {
	Name       string        `json:"name"`
	Age        time.Duration `json:"age"`
	Students   []Student     `json:"students"`
	MiddleName *string       `json:"middleName,omitempty"`
	University University    `json:"university"`
}

type University struct {
	Name    string `json:"name"`
	Address string `json:"address"`
}

type Student struct {
	Index string `json:"index"`
}

func main() {
	v := validation.New[Teacher](
		validation.For(func(t Teacher) string { return t.Name }).
			Rules(validation.NewSingleRule(func(name string) error { return fmt.Errorf("always fails") })),
	).WithName("Teacher")

	err := v.Validate(Teacher{})
	if err != nil {
		fmt.Println(err.WithName("Jake"))
	}

}

Output:

Validation for Jake has failed for the following properties:
  - always fails