Valix

Valix - Go package for validating requests

Overview
Installation
Features
Concepts
Examples
- Creating Validators
- Using Validators
Constraints
Polymorphic Validation
Validation Tags
I18n Support

Overview

Validate JSON requests in the form of *http.Request, map[string]interface{} or []interface{}

Installation

To install Valix, use go get:

go get github.com/marrow16/valix

To update Valix to the latest version, run:

go get -u github.com/marrow16/valix

Features

Deep validation (define validation for properties where those properties are objects or arrays of objects that also need validating)
Create validators from structs or define them as code (see Creating Validators)
Validate http.Request (into struct or map[string]interface{})
Finds all validation violations - not just the first one! (see Using Validators) and provides information for each violation (property name, path and message)
Rich set of pre-defined common constraints (see Common Constraints)
Customisable constraints (see Custom Constraints)
Conditional constraints to support partial polymorphic request models (see Conditional Constraints)
Full Polymorphic Validation
Support for i18n - enabling translation of validation messages (inc. http.Request language and region detection)
Validators fully marshalable and unmarshalable (save/share validators as JSON)
Highly extensible (add your own constraints, messages, presets etc. without a PR to this repository)
100% tested (see Codecov.io)
Coming soon - generate validators from OpenApi/Swagger JSON

Concepts

Valix is based on the concept that incoming API requests (such as POST, PUT etc.) should be validated early - against a definition of what the request body should look like.

At validation (of a JSON object as example) the following steps are performed:

Optionally check any constraints on the overall object (specified in Validator.Constraints)
Check if there are any unknown properties (unless Validator.IgnoreUnknownProperties is set to true)
For each defined property in Validator.Properties:
- Check the property is present (if PropertyValidator.Mandatory is set to true)
- Check the property value is non-null (if PropertyValidator.NotNull is set to true)
- Check the property value is of the correct type (if PropertyValidator.Type is set)
- Check the property value against constraints (specified in PropertyValidator.Constraints)
- If the property value is an object or array (and PropertyValidator.ObjectValidator is specified) - check the value using the validator (see top of this process)

The validator does not stop on the first problem it finds - it finds all problems and returns them as a list (slice) of 'violations'. Each violation has a message along with the name and path of the property that failed. However, custom constraints can be defined that will either stop the entire validation or cease further validation constraints on the current property

Examples

Creating Validators

Validators can be created from existing structs - adding v8n tags (in conjunction with existing json tags), for example:

package main

import (
    "github.com/marrow16/valix"
)

type AddPersonRequest struct {
    Name string `json:"name" v8n:"notNull,mandatory,constraints:[StringNoControlCharacters{},StringLength{Minimum: 1, Maximum: 255}]"`
    Age int `json:"age" v8n:"type:Integer,notNull,mandatory,constraint:PositiveOrZero{}"`
}
var AddPersonRequestValidator = valix.MustCompileValidatorFor(AddPersonRequest{}, nil)

(see Validation Tags for documentation on v8n tags)

Or in slightly more abbreviated form (using & to denote constraint tokens):

package main

import (
    "github.com/marrow16/valix"
)

type AddPersonRequest struct {
    Name string `json:"name" v8n:"notNull,mandatory,&StringNoControlCharacters{},&StringLength{Minimum: 1, Maximum: 255}"`
    Age int `json:"age" v8n:"type:Integer,notNull,mandatory,&PositiveOrZero{}"`
}
var AddPersonRequestValidator = valix.MustCompileValidatorFor(AddPersonRequest{}, nil)

The valix.MustCompileValidatorFor() function panics if the validator cannot be compiled. If you do not want a panic but would rather see the compilation error instead then use the valix.ValidatorFor() function instead.

Alternatively, Validators can be expressed effectively without a struct, for example:

package main

import (
    "github.com/marrow16/valix"
)

var CreatePersonRequestValidator = &valix.Validator{
    IgnoreUnknownProperties: false,
    Properties: valix.Properties{
        "name": {
            Type:         valix.JsonString,
            NotNull:      true,
            Mandatory:    true,
            Constraints:  valix.Constraints{
                &valix.StringNoControlCharacters{},
                &valix.StringLength{Minimum: 1, Maximum: 255},
            },
        },
        "age": {
            Type:         valix.JsonInteger,
            NotNull:      true,
            Mandatory:    true,
            Constraints:  valix.Constraints{
                &valix.PositiveOrZero{},
            },
        },
    },
}

Additional validator options

Validators can have additional properties that control the overall validation behaviour. These properties are described as follows:

Property	Description
`AllowArray`	(default `false`) Allows the validator to accept JSON arrays - and validate each item in the array Setting this option to `true` whilst leaving the `DisallowObject` option as `false` means that the validator will accept either a JSON array or object
`AllowNullJson`	Normally, a validator sees Null JSON (i.e. JSON string just containing the word `null`) as a violation - as it represents neither an object nor an array. Setting this option to `true` disables this behaviour (and results of successful validation may return a `nil` map/slice) NB. This option is only used by top-level validators
`DisallowObject`	(default `false`) Prevents the validator from accepting JSON objects Should only be set to `true` when `AllowArray` is also set to `true`
`IgnoreUnknownProperties`	Normally, a validator will report as a violation any properties not defined within the validator Setting this option to `true` means the validator will not check for unknown properties
`OrderedPropertyChecks`	Normally, a validator checks specified properties in an unpredictable order (as they are stored in a map). Setting this option to `true` means that the validator will check properties in order - by their `Order` field (or `order` tag) and then by name
`StopOnFirst`	Normally, a validator will find all constraint violations Setting this option to `true` causes the validator to stop when it finds the first violation NB. This option is only used by top-level validators
`UseNumber`	Validators use `json.NewDecoder()` to decode JSON Setting this option to `true` instructs the validator to call `Decoder.UseNumber()` prior to decoding NB. This option is only used by top-level validators

Using Validators

Once a validator has been created (using previous examples in Creating Validators), they can be used in several ways:

Validating a request into a struct

A request *http.Request can be validated into a struct:

package main

import (
    "encoding/json"
    "net/http"

    "github.com/marrow16/valix"
)

func AddPersonHandler(w http.ResponseWriter, r *http.Request) {
    addPersonReq := &AddPersonRequest{}
    ok, violations, _ := CreatePersonRequestValidator.RequestValidateInto(r, addPersonReq)
    if !ok {
        // write an error response with full info - using violations information
        valix.SortViolationsByPathAndProperty(violations)
        errResponse := map[string]interface{}{
            "$error": "Request invalid",
            "$details": violations,
        }
        w.WriteHeader(http.StatusUnprocessableEntity)
        w.Header().Set("Content-Type", "application/json")
        _ = json.NewEncoder(w).Encode(errResponse)
        return
    }
    // the addPersonReq will now be a validated struct
    w.Header().Set("Content-Type", "application/json")
    _ = json.NewEncoder(w).Encode(addPersonReq)
}

Validating a string or reader into a struct

A string, representing JSON, can be validated into a struct:

package main

import (
    "testing"

    "github.com/marrow16/valix"
    "github.com/stretchr/testify/require"
)

func TestValidateStringIntoStruct(t *testing.T) {
    str := `{
        "name": "",
        "age": -1
    }`
    req := &AddPersonRequest{}
    ok, violations, _ := AddPersonRequestValidator.ValidateStringInto(str, req)
    
    require.False(t, ok)
    require.Equal(t, 2, len(violations))
    valix.SortViolationsByPathAndProperty(violations)
    require.Equal(t, "Value must be positive or zero", violations[0].Message)
    require.Equal(t, "age", violations[0].Property)
    require.Equal(t, "", violations[0].Path)
    require.Equal(t, "String value length must be between 1 and 255 (inclusive)", violations[1].Message)
    require.Equal(t, "name", violations[1].Property)
    require.Equal(t, "", violations[1].Path)
    
    str = `{
        "name": "Bilbo Baggins",
        "age": 25
    }`
    ok, violations, _ = AddPersonRequestValidator.ValidateStringInto(str, req)
    
    require.True(t, ok)
    require.Equal(t, 0, len(violations))
    require.Equal(t, "Bilbo Baggins", req.Name)
    require.Equal(t, 25, req.Age)
}

Also, a reader io.Reader can be validated into a struct using the .ValidateReaderIntoStruct() method of the validator:

package main

import (
    "strings"
    "testing"

    "github.com/marrow16/valix"
    "github.com/stretchr/testify/require"
)

func TestValidateReaderIntoStruct(t *testing.T) {
	reader := strings.NewReader(`{
		"name": "",
		"age": -1
	}`)
	req := &AddPersonRequest{}

	ok, violations, _ := AddPersonRequestValidator.ValidateReaderInto(reader, req)

	require.False(t, ok)
	require.Equal(t, 2, len(violations))
	valix.SortViolationsByPathAndProperty(violations)
	require.Equal(t, "Value must be positive or zero", violations[0].Message)
	require.Equal(t, "age", violations[0].Property)
	require.Equal(t, "", violations[0].Path)
	require.Equal(t, "String value length must be between 1 and 255 (inclusive)", violations[1].Message)
	require.Equal(t, "name", violations[1].Property)
	require.Equal(t, "", violations[1].Path)

	reader = strings.NewReader(`{
		"name": "Bilbo Baggins",
		"age": 25
	}`)
	ok, violations, _ = AddPersonRequestValidator.ValidateReaderInto(reader, req)

	require.True(t, ok)
	require.Equal(t, 0, len(violations))
	require.Equal(t, "Bilbo Baggins", req.Name)
	require.Equal(t, 25, req.Age)
}

Validating a map

Validators can also validate a map[string]interface{} representation of a JSON object:

package main

import (
    "testing"

    "github.com/marrow16/valix"
    "github.com/stretchr/testify/require"
)

func TestValidateMap(t *testing.T) {
    req := map[string]interface{}{
        "name": "",
        "age": -1,
    }
  
    ok, violations := AddPersonRequestValidator.Validate(req)
    require.False(t, ok)
    require.Equal(t, 2, len(violations))
    valix.SortViolationsByPathAndProperty(violations)
    require.Equal(t, "Value must be positive or zero", violations[0].Message)
    require.Equal(t, "age", violations[0].Property)
    require.Equal(t, "", violations[0].Path)
    require.Equal(t, "String value length must be between 1 and 255 (inclusive)", violations[1].Message)
    require.Equal(t, "name", violations[1].Property)
    require.Equal(t, "", violations[1].Path)
  
    req = map[string]interface{}{
        "name": "Bilbo Baggins",
        "age": 25,
    }
    ok, _ = AddPersonRequestValidator.Validate(req)
    require.True(t, ok)
}

Validating a slice

Validators can also validate a slice []interface{} representation of a JSON object, where each object element in the slice is validated:

package main

import (
    "testing"

    "github.com/marrow16/valix"
    "github.com/stretchr/testify/require"
)

func TestValidateSlice(t *testing.T) {
    req := []interface{}{
        map[string]interface{}{
            "name": "",
            "age":  -1,
        },
        map[string]interface{}{
            "name": "Bilbo Baggins",
            "age":  25,
        },
    }
  
    ok, violations := AddPersonRequestValidator.ValidateArrayOf(req)
    require.False(t, ok)
    require.Equal(t, 2, len(violations))
    valix.SortViolationsByPathAndProperty(violations)
    require.Equal(t, "Value must be positive or zero", violations[0].Message)
    require.Equal(t, "age", violations[0].Property)
    require.Equal(t, "[0]", violations[0].Path)
    require.Equal(t, "String value length must be between 1 and 255 (inclusive)", violations[1].Message)
    require.Equal(t, "name", violations[1].Property)
    require.Equal(t, "[0]", violations[1].Path)
  
    req = []interface{}{
        map[string]interface{}{
            "name": "Frodo Baggins",
            "age":  20,
        },
        map[string]interface{}{
            "name": "Bilbo Baggins",
            "age":  25,
        },
    }
    ok, _ = AddPersonRequestValidator.ValidateArrayOf(req)
    require.True(t, ok)
}

Constraints

In Valix, a constraint is a particular validation rule that must be satisfied. For a constraint to be used by the validator it must implement the valix.Constraint interface.

Common Constraints

Valix provides a rich set of over 100 pre-defined common constraints (plus many common regex patterns) - see Constraints Reference wiki documentation for full reference with examples.

Constraint Sets

It is not uncommon in APIs for many properties in different requests to share a common set of constraints. For this reason, Valix provides a ConstraintSet - which is itself a Constraint but contains a list of sub-constraints.

type ConstraintSet struct {
    Constraints Constraints
    Message string
}

When checking a ConstraintSet, the contained constraints are checked sequentially but the overall set stops on the first failing constraint.

If a Message is provided (non-empty string) then that message is used for any of the failing constraints - otherwise the individual constraint fail messages are used.

The following is an example of a constraint set which imposes a complex constraint (although one that could probably be more easily achieved using valix.StringPattern)

package main

import (
    "unicode"
    "github.com/marrow16/valix"
)

var MySet = &valix.ConstraintSet{
    Constraints: valix.Constraints{
        &valix.StringTrim{},
        &valix.StringNotEmpty{},
        &valix.StringLength{Minimum: 16, Maximum: 64},
        valix.NewCustomConstraint(func(value interface{}, vcx *valix.ValidatorContext, this *valix.CustomConstraint) (bool, string) {
            if str, ok := value.(string); ok {
                if len(str) == 0 || str[0] < 'A' || str[0] > 'Z' {
                    return false, this.GetMessage(vcx)
                }
            }
            return true, ""
        }, ""),
        &valix.StringCharacters{
            AllowRanges: []unicode.RangeTable{
                {R16: []unicode.Range16{{'0', 'z', 1}}},
            },
            DisallowRanges: []unicode.RangeTable{
                {R16: []unicode.Range16{{0x003a, 0x0040, 1}}},
                {R16: []unicode.Range16{{0x005b, 0x005e, 1}}},
                {R16: []unicode.Range16{{0x0060, 0x0060, 1}}},
            },
        },
    },
    Message: "String value length must be between 16 and 64 chars; must be letters (upper or lower), digits or underscores; must start with an uppercase letter",
}

Constraint sets can also be registered, making them available in v8n struct tags.

Custom Constraints

If you need a constraint for a specific domain validation, there are two ways to do this...

Create a re-usable constraint (which implements the valix.Constraint interface), example:

package main

import (
    "strings"
    "github.com/marrow16/valix"
)

type NoFoo struct {
}

func (c *NoFoo) Check(value interface{}, vcx *valix.ValidatorContext) (bool, string) {
    if str, ok := value.(string); ok {
        return !strings.Contains(str, "foo"), c.GetMessage(vcx)
    }
    return true, ""
}

func (c *NoFoo) GetMessage(tcx I18nContext) string {
    return "Value must not contain \"foo\""
}

Or create a custom constraint on the fly with check function, example:
Note: Custom constraints using functions means that the validator cannot be marshalled/unmarshalled

package main

import (
    "strings"
    "github.com/marrow16/valix"
)

var myValidator = &valix.Validator{
    IgnoreUnknownProperties: false,
    Properties: valix.Properties{
        "foo": {
            Type:         valix.JsonString,
            NotNull:      true,
            Mandatory:    true,
            Constraints:  valix.Constraints{
                valix.NewCustomConstraint(func(value interface{}, vcx *valix.ValidatorContext, cc *valix.CustomConstraint) (bool, string) {
                    if str, ok := value.(string); ok {
                        return !strings.Contains(str, "foo"), cc.GetMessage(vcx)
                    }
                    return true, ""
                }, "Value must not contain \"foo\""),
            },
        },
    },
}

Constraints Registry

All of the Valix common constraints are loaded into a registry - the registry enables the v8n tags to reference these.

If you want to make your own custom constraint available for use in v8n tags, it must also be registered. For example:

package main

import (
    "strings"
    "github.com/marrow16/valix"
)

func init() {
    valix.RegisterConstraint(&NoFoo{})
}

// and the constraint can now be used in `v8n` tag...
type MyRequest struct {
    Name string `json:"name" v8n:"&NoFoo{}"`
}

Required/Unwanted Properties

When properties are required, or unwanted, according to the presence of other properties - use the v8n tag tokens required_with:<expr> or unwanted_with:<expr> (abbreviated forms +: and -: respectively).

The simplest expression is just the name of another property - the following example shows making two properties foo and bar mutually inclusive (i.e. if one is present then the other is required):

type ExampleMutuallyInclusive struct {
    Foo string `json:"foo" v8n:"+:bar, +msg:'foo required when bar present'"`
    Bar string `json:"bar" v8n:"+:foo, +msg:'bar required when foo present'"`
}

Or another example, using the unwanted_with: token, to make two properties mutually exclusive (i.e. if one is present then the other must not):

type ExampleMutuallyExclusive struct {
    Foo string `json:"foo" v8n:"-:bar, -msg:'foo and bar are mutually exclusive'"`
    Bar string `json:"bar" v8n:"-:foo, -msg:'foo and bar are mutually exclusive'"`
}

The required_with: and unwanted_with can also use more complex boolean expressions - the following example demonstrates making two out of three properties mutually inclusive but not all three:

type ExampleTwoOfThreeMutuallyInclusive struct {
    Foo string `json:"foo" v8n:"+:(bar || baz) && !(bar && baz), -:bar && baz"`
    Bar string `json:"bar" v8n:"+:(foo || baz) && !(foo && baz), -:foo && baz"`
    Baz string `json:"baz" v8n:"+:(foo || bar) && !(foo && bar), -:foo && bar"`
}

The boolean property expressions can also traverse up and down the object tree (using JSON . path style notation). The following demonstrates:

type ExampleUpAndDownRequired struct {
    Foo string `json:"foo" v8n:"+:sub.foo"`
    Bar string `json:"bar" v8n:"+:sub.bar"`
    Sub struct {
        SubFoo string `json:"foo" v8n:"+:..foo"`
        SubBar string `json:"bar" v8n:"+:..bar"`
    } `json:"sub"`
}

Additional expression functionality notes:

Boolean operator ^^ (XOr) is also supported
Path traversal also supports going up to the root object - e.g. /.foo.bar will go up to the root object and then descend down path foo.bar
Prefixing property name with ~ (tilde) means check a context condition rather than property existence - e.g. ~METHOD_POST checks whether the METHOD_POST condition token has been set in the context
The +: and -: validation tag tokens correspond to the valix.PropertyValidator.RequiredWith and valix.PropertyValidator.UnwantedWith fields respectively
Use the valix.ParseExpression or valix.MustParseExpression functions to programmatically parse boolean property expressions
Unfortunately, array index notation (e.g. sub[0]) is not currently supported (and neither is traversing array values)

Conditional Constraints

Sometimes, the model of JSON requests needs to vary according to some property condition. For example, the following is a beverage order for a tea and coffee shop:

type BeverageOrder struct {
    Type     string `json:"type" v8n:"notNull,required,&StringValidToken{Tokens:['tea','coffee']}"`
    Quantity int    `json:"quantity" v8n:"notNull,required,&Positive{}"`
    // only relevant to type="tea"...
    Blend    string `json:"blend" v8n:"notNull,required,&StringValidToken{Tokens:['Earl Grey','English Breakfast','Masala Chai']}"`
    // only relevant to type="coffee"...
    Roast    string `json:"roast" v8n:"notNull,required,&StringValidToken{Tokens:['light','medium','dark']}"`
}

The above validation will always expect the blend and roast properties to be present and their value to be valid. However, this is not the requirement of the model - we only want:

the blend property to be present and valid when type="tea"
the 'roast' property to be present and valid when type="coffee"

These validation requirements can be incorporated by using the 'when conditions':

type BeverageOrder struct {
    Type     string `json:"type" v8n:"notNull,required,order:-1,&StringValidToken{Tokens:['tea','coffee']},&SetConditionFrom{Parent:true}"`
    Quantity int    `json:"quantity" v8n:"notNull,required,&Positive{}"`
    // only relevant to type="tea"...
    Blend    string `json:"blend" v8n:"when:tea,notNull,required,&StringValidToken{Tokens:['Earl Grey','English Breakfast','Masala Chai']}"`
    // only relevant to type="coffee"...
    Roast    string `json:"roast" v8n:"when:coffee,notNull,required,&StringValidToken{Tokens:['light','medium','dark']}"`
}

Note in the above:

on the Type field:
- order:-1 means that this property is checked
- &SetConditionFrom{} sets a validator context condition token from the incoming value of property type
  therefore, either a validator condition token of tea or coffee will be set
  Note: the Parent:true means properties at the same level as this will see the condition token
on the Blend field the when:tea tag has been added - which means the blend property is only checked when there is a validator condition token of tea set
on the Roast field the when:coffee tag has been added - which means the roast property is only checked when there is a validator condition token of coffee set

However, this second example may still not be strict enough - because it allows the blend property to be present when the type is "coffee" and the roast property to be present when the type is "tea"
This can be overcome by using the 'unwanted conditions':

type BeverageOrderStrict struct {
    Type     string `json:"type" v8n:"notNull,required,order:-1,&StringValidToken{Tokens:['tea','coffee']},&SetConditionFrom{Parent:true}"`
    Quantity int    `json:"quantity" v8n:"notNull,required,&Positive{}"`
    // Blend is only relevant when type="tea"...
    Blend    string `json:"blend" v8n:"when:tea,unwanted:!tea,notNull,required,&StringValidToken{Tokens:['Earl Grey','English Breakfast','Masala Chai']}"`
    // Roast is only relevant when type="coffee"...
    Roast    string `json:"roast" v8n:"when:coffee,unwanted:!coffee,notNull,required,&StringValidToken{Tokens:['light','medium','dark']}"`
}

Note in the above:

the unwanted:!tea tag has been added to the Blend field - which means... "if condition token of tea has not been set then we do not want the blend property to be present"
the unwanted:!coffee tag has been added to the Roast field - which means... "if condition token of coffee has not been set then we do not want the roast property to be present"

Polymorphic Validation

Sometimes, the model of JSON requests needs to vary completely according to some condition. The previous conditional constraints example can solve some of the conditional variance - but when different properties are required/not-required or same properties have different constraints under different conditions then polymorphic validation becomes necessary.

As an example, if the following requests all need to be validated using a single validator:

{
    "type": "tea",
    "quantity": 1,
    "blend": "Earl Grey|English Breakfast|Masala Chai"
}

{
    "type": "coffee",
    "quantity": 1,
    "roast": "light|medium|dark"
}

{
    "type": "soft",
    "quantity": 1,
    "brand": "Coca Cola",
    "flavor": "Regular|Diet|Zero|Cherry"
}

{
    "type": "soft",
    "quantity": 1,
    "brand": "Tango",
    "flavor": "Orange|Apple|Strawberry|Watermelon|Tropical"
}

A demonstrated solution to this can be see in the Polymorphic example code

Note: Polymorphic validators cannot be derived from struct tags (see Validation Tags) - because structs themselves cannot be polymorphic!

Validation Tags

Valix can read tags from struct fields when building validators. These are the v8n tags, in the format:

type example struct {
    Field string `v8n:"token[,token, ...]"`
}

Where the tokens correspond to various property validation options - as listed here:

Token	Purpose & Example
`constraint:constraint-name{fields...}`	Adds a constraint to the property (this token can be specified multiple times within the `v8n` tag. The `constraint-name` must be a Valix common constraint or a previously registered constraint. The constraint `fields` can optionally be set. Example type Example struct { Foo string `v8n:"constraint:StringMaxLength{Value:255}"` }
`constraints:[constraint-name{},...]`	Adds multiple constraints to the property Example type Example struct { Foo string `v8n:"constraints:[StringNotEmpty{},StringNoControlCharacters{}]"` }
`&constraint-name{fields...}`	Adds a constraint to the property (shorthand way of specifying constraint without `constraint:` or `constraints:[]` prefix) Example type Example struct { Foo string `v8n:"&StringMaxLength{Value:255}"` }
`&[condition,...]constraint-name{fields...}`	Adds a conditional constraint to the property - the constraint is only checked when the condition(s) are met Example type Example struct { Foo string `v8n:"&[METHOD_POST]StringNotEmpty{}"` } The `StringNotEmpty` constraint is only checked when the `METHOD_POST` condition token has been set
`&<expr>constraint-name{fields...}`	Adds a conditional constraint to the property - the constraint is only checked when the `expr` evaluates to true Example type Example struct { Foo string `json:"foo" v8n:"&<(bar && !baz) \|\| (!bar && baz)>StringNotEmpty{}"` Bar string `json:"bar" v8n:"optional"` Baz string `json:"baz" v8n:"optional"` } The `StringNotEmpty` constraint is only checked when only one of the `bar` or `baz` properties are present
`mandatory`	Specifies the JSON property must be present Example type Example struct { Foo string `v8n:"mandatory"` }
`mandatory:condition` or `mandatory:[condition,...]`	Specifies the JSON property must be present under specified conditions Example type Example struct { Foo string `v8n:"mandatory:[METHOD_POST,METHOD_PATCH]"` }
`required_with:expr` or `+:expr`	Specifies the JSON property is required according to the presence/non-presence of other properties (as determined by the `expr`) You can also control the violation message used when the property is required but missing using a `required_with_msg:` or `+msg:` tag token Example type Example struct { Foo string `json:"foo" v8n:"required_with:bar && baz,+msg:'Sometimes foo is required'"` Bar string `json:"bar"` Baz string `json:"baz"` } Means the property `foo` is required when both `bar` and `baz` properties are present Use `+msg` or `required_with_msg` to alter the message used when this constraint fails (see also Required/Unwanted Properties for further notes and examples on expressions)
`unwanted_with:expr` or `-:expr`	Specifies the JSON property is unwanted according to the presence/non-presence of other properties (as determined by the `expr`) You can also control the violation message used when the property is present but unwanted using a `unwanted_with_msg:` or `-msg:` tag token Example type Example struct { Foo string `json:"foo" v8n:"unwanted_with:bar \|\| baz,-msg:'Sometimes foo is unwanted'"` Bar string `json:"bar"` Baz string `json:"baz"` } Means the property `foo` is unwanted when either the `bar` or `baz` properties are present Use `-msg` or `unwanted_with_msg` to alter the message used when this constraint fails (see also Required/Unwanted Properties for further notes and examples on expressions)
`notNull`	Specifies the JSON value for the property cannot be null Example type Example struct { Foo string `v8n:"notNull"` }
`nullable`	Specifies the JSON value for the property can be null (opposite of `notNull`) Example type Example struct { Foo string `v8n:"nullable"` }
`optional`	Specifies the JSON property does not have to be present (opposite of `mandatory`) Example type Example struct { Foo string `v8n:"optional"` }
`order:n`	Specifies the order in which the property should be validated (only respected if parent object is tagged as `obj.ordered` or parent validator is set to `OrderedPropertyChecks`) Example type Example struct { Foo string `v8n:"order:0"` Bar string `v8n:"order:1"` }
`only` or `only:condition` or `only:[condition,...]`	Specifies that the property must not be present with other properties Example type Example struct { Foo string `v8n:"only,mandatory"` Bar string `v8n:"only,mandatory"` Baz string `v8n:"only,mandatory"` } In the above example, a request with only one of the `Foo`, `Bar` or `Baz` will be valid - specifying more than one of those properties would cause a violation. Note that even though all three properties are mandatory - if only one of the properties is present, then the other mandatories are ignored. Use `only_msg` to alter the message used when this constraint fails
`required`	same as `mandatory` Example type Example struct { Foo string `v8n:"required"` }
`required:condition` or `required:[condition,...]`	same as `mandatory:condition` Example type Example struct { Foo string `v8n:"required:[METHOD_POST,METHOD_PATCH]"` }
`stop_on_first` or `stop1st`	Specifies that property validation to stop at the first constraint violation found Note: This would be the equivalent of setting `Stop` on each constraint Example type Example struct { Foo string `v8n:"stop_on_first,&StringNotBlank{},&StringNotEmpty{}"` } In the above example, only one of the specified constraints would fail
`type:type`	Specifies (overrides) the type expected for the JSON property value Where `type` must be one of (case-insensitive): `string`, `number`, `integer`, `boolean`, `object`, `array` or `any` Example type Example struct { Foo json.Number `v8n:"type:integer"` }
`when:condition` or `when:[condition,...]`	Adds when condition(s) for the property - where `condition` is a condition token (that may have been set during validation) The property is only validated when these conditions are met (see Conditional Constraints) Example type Example struct { Foo string `v8n:"when:YES_FOO"` }
`unwanted:condition` or `unwanted:[condition,...]`	Adds unwanted condition(s) for the property - where `condition` is a condition token (that may have been set during validation) If the unwanted condition(s) is met but the property is present then this is a validation violation (see Conditional Constraints) Example type Example struct { Foo string `v8n:"unwanted:NO_FOO"` }
`obj.ignoreUnknownProperties`	Sets an object (or array of objects) to ignore unknown properties (ignoring unknown properties means that the validator will not fail if an unknown property is found) Example type Example struct { SubObj struct{ Foo string } `json:"subObj" v8n:"obj.ignoreUnknownProperties"` }
`obj.unknownProperties:true\|false`	Sets whether an object is to allow/ignore (`true`) or disallow (`false`) unknown properties Example type Example struct { SubObj struct{ Foo string } `json:"subObj" v8n:"obj.unknownProperties:false"` }
`obj.constraint:constraint-name{}`	Sets a constraint on an entire object or array Example type Example struct { SubObj struct{ Foo string } `json:"subObj" v8n:"obj.constraint:Length{Minimum:1,Maximum:16}"` }
`obj.ordered`	Sets the object validator to check properties in order (same as `Validator.OrderedPropertyChecks` in Additional validator options) Example type Example struct { SubObj struct{ Foo string `v8n:"order:0"` Bar string `v8n:"order:1"` } `v8n:"obj.ordered"` } the above will check the properties in order specified by their `order:` - whereas the following will check the properties in alphabetical order of name... type Example struct { SubObj struct{ Foo string `json:"foo"` Bar string `json:"bar"` } `v8n:"obj.ordered"` }
`obj.when:condition` or `obj.when:[condition,...]`	Adds when condition(s) for the object or array - where `condition` is a condition token (that may have been set during validation) The object/array is only validated when these conditions are met (see Conditional Constraints) Example type Example struct { SubObj struct{ Foo string } `json:"subObj" v8n:"obj.when:YES_SUB"` }
`arr.allowNulls`	For array (slice) fields, specifies that array elements can be null Example type Example struct { SubSlice []*struct { Foo string } `json:"subSlice" v8n:"arr.allowNulls"` }

Registering your own tag tokens

The v8n tag can also support custom tokens which can be registered using valix.RegisterCustomTagToken. Any registered custom tag tokens can be used in the v8n tag and will be processed when building a validator for a struct using valix.ValidatorFor

An example of how this is used can be found in examples/custom_tag_tokens_test.go

Tag token aliases

If you find that you're using the same v8n tag tokens repeatedly - you can create aliases for these and then just reference the alias using a $ prefix.

An example of how this is used can be found in examples/tag_aliases_test.go

Abbreviating constraints in tags

When specifying constraints in tags, especially with constraint args, the struct tags can become a little verbose. For example:

type MyStruct struct {
    Foo string `json:"foo" v8n:"&StringNoControlCharacters{},&StringUppercase{Message:'Upper only'},&StringLength{Minimum:10,Maximum:20,ExclusiveMin:true}"`
}

To overcome this, there are several things you can do:

Where there are no args for the constraint, the {} at the end can be dropped
Where the constraint struct has only one field or has a default field (tagged with `v8n:"default"`) then the arg name can be dropped
The constraints registry has pre-defined abbreviated forms
Constraint arg names can be abbreviated or shortened to closest matching name, e.g.
1. Message can be abbreviated to Msg or msg (case-insensitive, remove vowels, replace double-characters with single)
2. Minimum can be shortened to Min or min (or any other variation that matches only one target field name)
3. ExclusiveMin can be shortened to excMin, exMin, eMin etc.
Where a constraint field is a bool and setting it to true - the value (:true) can be omitted

After those steps, the constraint tags would be:

type MyStruct struct {
    Foo string `json:"foo" v8n:"&strnocc,&strupper{'Upper only'},&strlen{stp,min:10,max:20,excMin}"`
}

Internationalisation Support

Valix has full I18n support for translating violation messages - which is both extensible and/or replaceable...

I18n support features:

Support for both language and region (e.g. en, en-GB, en-US, fr and fr-CA etc.)
Detection of request Accept-Language header
(when using Validator.RequestValidate or Validator.RequestValidateInto)
Fallback language and region support
- e.g. if fr-CA was requested but no Canadian specific translation then fr is used
- e.g. if mt (Maltese) is an unsupported language but you want the fallback language to be it (Italian) then set this in the valix.DefaultFallbackLanguages variable, e.g. valix.DefaultFallbackLanguages["mt"] = "it"
Default runtime language and region changeable
(set vars valix.DefaultLanguage and/or valix.DefaultRegion)
Built-in valix.DefaultTranslator supports English, French, German, Italian and Spanish
- more languages and regional variants can be added at runtime
- replace translator with your own (implementing valix.Translator interface)
Completely replaceable I18n support (replace variable valix.DefaultI18nProvider with your own)

marrow16/valix

marrow16

Reviews

Repository Details