vjson

vjson is a Go package that helps to validate JSON objects in a declarative way.

Getting Started

Installing

For installing vjson, use command below:

go get -u github.com/miladibra10/vjson

Concepts

There are two main concepts in vjson that are:

Schema
Field

Schema

A schema is the holder of JSON object specifications. It contains the way of validation of a JSON object. a schema consists of an array of fields.

Field

A field contains characteristics of a specific field of a json object. multiple field types are supported by vjson. list of supported types are:

integer
float
string
boolean
array
object
null
or

How to create a Schema

There are two ways to create a schema.

Schema could be declared in code in a declarative manner.
Schema could be parsed from a file or string.

Schema in code

Schema could be declared in code like this:

package main

import "github.com/miladibra10/vjson"

func main() {
	schema := vjson.NewSchema(
		vjson.String("name").Required(),
	)

	jsonString := `
	{
		"name": "James"
	}
	`

	err := schema.ValidateString(jsonString)
	if err != nil {
		panic(err)
	}
}

schema object contains a string field, named name. This code validates jsonString.

Parse Schema

Schema could be parsed from a file or a string. These methods help to parse schema.

ReadFromString(input string): receives characteristics of a schema in a string format and returns a schema object and an error.
ReadFromBytes(input []byte): receives characteristics of a schema in a byte array format and returns a schema object and an error.
ReadFromFile(filePath string): receives file path of json file which contains characteristics of a schema, and returns a schema object and an error.

Format of schema for parsing should be a json like this:

{
  "fields": [
    ...
  ]
}

fields should contain field specifications.

This code parses a schema from string:

package main

import "github.com/miladibra10/vjson"

func main() {
	schemaStr := `
	{
		"fields": [
			{
				"name": "name",
				"type": "string"
				"required": true
			}
		]
	}
	`
	schema, err := vjson.ReadFromString(schemaStr)
	if err != nil {
		panic(err)
	}

	jsonString := `
	{
		"name": "James"
	}
	`

	err = schema.ValidateString(jsonString)
	if err != nil {
		panic(err)
	}
}

schemaStr describes the schema and vjson.ReadFromString(schemaStr) parses the string and returns a schema object.

schema object contains a string field, named name. This code validates jsonString.

Note: You could Marshal your schema as a json object for backup usages with json.Marshal function.

Fields

Integer

An integer field could be created in code like this:

vjson.Integer("foo")

some validation characteristics could be added to an integer field with chaining some functions:

Required() sets the field as a required field. validation will return an error if a required field is not present in json object.
Min(min int) forces the integer field to be greater than min in validating json object.
Max(max int) forces the integer field to be lower than max in validating json object.
Positive() checks if the value of field is positive.
Negative() checks if the value of field is negative.
Range(start, end int) adds a range for integer field. the value of json field should be within this range.

integer field could be described by a json for schema parsing.

name: the name of the field
type: type value for integer field must be integer
required: whether the field is required or not
min: minimum value of field
max: maximum value of field
positive: a boolean that describes that a field is positive or negative (true for positive and false for negative)
ranges: an array of ranges to be checked in field validation.

Example

an integer field, named foo which is required, minimum value should be 2, maximum value should be 10, should be positive and be within range [3,5] or [6,8] ,could be declared like this:

Code

vjson.Integer("foo").Required().Min(2).Max(10).Positive().Range(3,5).Range(6,8)

File

{
  "name": "foo",
  "type": "integer",
  "required": true,
  "min": 2,
  "max": 10,
  "positive": true,
  "ranges": [
    {
      "start": 3,
      "end": 5
    },
    {
      "start": 6,
      "end": 8
    }
  ]
}

Float

A float field could be created in code like this:

vjson.Float("foo")

some validation characteristics could be added to a float field with chaining some functions:

Required() sets the field as a required field. validation will return an error if a required field is not present in json object.
Min(min float64) forces the float field to be greater than min in validating json object.
Max(max float64) forces the float field to be lower than max in validating json object.
Positive() checks if the value of field is positive.
Negative() checks if the value of field is negative.
Range(start, end float64) adds a range for float field. the value of json field should be within this range.

float field could be described by a json for schema parsing.

name: the name of the field
type: type value for float field must be float
required: whether the field is required or not
min: minimum value of field
max: maximum value of field
positive: a boolean that describes that a field is positive or negative (true for positive and false for negative)
ranges: an array of ranges to be checked in field validation.

Example

a float field, named foo which is required, minimum value should be 2.5, maximum value should be 10.5, should be positive and be within range [3,5] or [6,8] ,could be declared like this:

Code

vjson.Float("foo").Required().Min(2.5).Max(10.5).Positive().Range(3,5).Range(6,8)

File

{
  "name": "foo",
  "type": "float",
  "required": true,
  "min": 2.5,
  "max": 10.5,
  "positive": true,
  "ranges": [
    {
      "start": 3,
      "end": 5
    },
    {
      "start": 6,
      "end": 8
    }
  ]
}

String

A string field could be created in code like this:

vjson.String("foo")

some validation characteristics could be added to a string field with chaining some functions:

Required() sets the field as a required field. validation will return an error if a required field is not present in json object.
MinLength(min int) forces the length of string field to be greater than min in validating json object.
MaxLength(max int) forces the length of string field to be lower than max in validating json object.
Format(format string) gets a regex format and checks if value of json object matches the format.
Choices(choice ...string) checks if the value of string field is equal to one of choices.

float field could be described by a json for schema parsing.

name: the name of the field
type: type value for string field must be string
required: whether the field is required or not
min_length: minimum length of string value of field
max_length: maximum length of string value of field
format: a regex format and checks if value of json object matches the format.
choices: a list of strings that value of field should be equal to one of them.

Example

a string field, named foo which is required, minimum length value should be 2, maximum length value should be 10, should be Equal to one of these values: first, second could be declared like this:

Code

vjson.String("foo").Required().MinLength(2).MaxLength(10).Choices("first", "second")

File

{
  "name": "foo",
  "type": "string",
  "required": true,
  "min_length": 2,
  "max_length": 10,
  "choices": [
    "first",
    "second"
  ]
}

Boolean

A boolean field could be created in code like this:

vjson.Boolean("foo")

some validation characteristics could be added to a boolean field with chaining some functions:

Required() sets the field as a required field. validation will return an error if a required field is not present in json object.
ShouldBe(value bool) forces the value of field be equal to value

boolean field could be described by a json for schema parsing.

name: the name of the field
type: type value for boolean field must be boolean
required: whether the field is required or not
value: a boolean (same sa ShouldBe in code) that describes that the value of json field.

Example

a boolean field, named foo which is required, and always should be false, could be declared like this:

Code

vjson.Boolean("foo").Required().ShouldBe(false)

File

{
  "name": "foo",
  "type": "boolean",
  "required": true,
  "value": false
}

Array

An array field could be created in code like this:

vjson.Array("foo", vjson.String("item"))

the first argument is the name of array field, and the second one is the field characteristics of each item of array.

some validation characteristics could be added to an array field with chaining some functions:

Required() sets the field as a required field. validation will return an error if

Vjson

Install / Use

README

vjson

Getting Started

Installing

Concepts

Schema

Field

How to create a Schema

Schema in code

Parse Schema

Fields

Integer

Example

Code

File

Float

Example

Code

File

String

Example

Code

File

Boolean

Example

Code

File

Array