jsonschema

README

jsonschema

Package jsonschema provides json-schema compilation and validation.

This implementation of JSON Schema, supports draft4, draft6 and draft7.

Passes all tests(including optional) in https://github.com/json-schema/JSON-Schema-Test-Suite

An example of using this package:

schema, err := jsonschema.Compile("schemas/purchaseOrder.json")
if err != nil {
    return err
}
f, err := os.Open("purchaseOrder.json")
if err != nil {
    return err
}
defer f.Close()
if err = schema.Validate(f); err != nil {
    return err
}

The schema is compiled against the version specified in $schema property. If $schema property is missing, it uses latest draft which currently is draft7. You can force to use draft4 when $schema is missing, as follows:

compiler := jsonschema.NewCompiler()
compler.Draft = jsonschema.Draft4

you can also validate go value using schema.ValidateInterface(interface{}) method.
but the argument should not be user-defined struct.

This package supports loading json-schema from filePath and fileURL.

To load json-schema from HTTPURL, add following import:

import _ "github.com/santhosh-tekuri/jsonschema/httploader"

Loading from urls for other schemes (such as ftp), can be plugged in. see package jsonschema/httploader for an example

To load json-schema from in-memory:

data := `{"type": "string"}`
url := "sch.json"
compiler := jsonschema.NewCompiler()
if err := compiler.AddResource(url, strings.NewReader(data)); err != nil {
    return err
}
schema, err := compiler.Compile(url)
if err != nil {
    return err
}
f, err := os.Open("doc.json")
if err != nil {
    return err
}
defer f.Close()
if err = schema.Validate(f); err != nil {
    return err
}

This package supports json string formats:

• date-time
• date
• time
• hostname
• email
• ip-address
• ipv4
• ipv6
• uri
• uriref/uri-reference
• regex
• format
• json-pointer
• relative-json-pointer
• uri-template (limited validation)

Developers can register their own formats using package "github.com/santhosh-tekuri/jsonschema/formats".

"base64" contentEncoding is supported. Custom decoders can be registered using package "github.com/santhosh-tekuri/jsonschema/decoders".

"application/json" contentMediaType is supported. Custom mediatypes can be registered using package "github.com/santhosh-tekuri/jsonschema/mediatypes".

ValidationError

The ValidationError returned by Validate method contains detailed context to understand why and where the error is.

schema.json:

{
      "$ref": "t.json#/definitions/employee"
}

t.json:

{
    "definitions": {
        "employee": {
            "type": "string"
        }
    }
}

doc.json:

1

Validating doc.json with schema.json, gives following ValidationError:

I[#] S[#] doesn't validate with "schema.json#"
  I[#] S[#/$ref] doesn't valide with "t.json#/definitions/employee"
    I[#] S[#/definitions/employee/type] expected string, but got number

Here I stands for instance document and S stands for schema document.
The json-fragments that caused error in instance and schema documents are represented using json-pointer notation.
Nested causes are printed with indent.

CLI

jv <schema-file> [<json-doc>]...

if no <json-doc> arguments are passed, it simply validates the <schema-file>.

exit-code is 1, if there are any validation errors

Documentation

Overview

Package jsonschema provides json-schema compilation and validation.

This implementation of JSON Schema, supports draft4, draft6 and draft7. Passes all tests(including optional) in https://github.com/json-schema/JSON-Schema-Test-Suite

An example of using this package:

schema, err := jsonschema.Compile("schemas/purchaseOrder.json")
if err != nil {
	return err
}
f, err := os.Open("purchaseOrder.json")
if err != nil {
	return err
}
defer f.Close()
if err = schema.Validate(f); err != nil {
	return err
}

The schema is compiled against the version specified in `$schema` property. If `$schema` property is missing, it uses latest draft which currently is draft7. You can force to use draft4 when `$schema` is missing, as follows:

compiler := jsonschema.NewCompiler()
compler.Draft = jsonschema.Draft4

you can also validate go value using schema.ValidateInterface(interface{}) method. but the argument should not be user-defined struct.

This package supports loading json-schema from filePath and fileURL.

To load json-schema from HTTPURL, add following import:

import _ "github.com/santhosh-tekuri/jsonschema/httploader"

Loading from urls for other schemes (such as ftp), can be plugged in. see package jsonschema/httploader for an example

To load json-schema from in-memory:

data := `{"type": "string"}`
url := "sch.json"
compiler := jsonschema.NewCompiler()
if err := compiler.AddResource(url, strings.NewReader(data)); err != nil {
	return err
}
schema, err := compiler.Compile(url)
if err != nil {
	return err
}
f, err := os.Open("doc.json")
if err != nil {
	return err
}
defer f.Close()
if err = schema.Validate(f); err != nil {
	return err
}

This package supports json string formats: date-time, date, time, hostname, email, ip-address, ipv4, ipv6, uri, uriref, regex, format, json-pointer, relative-json-pointer, uri-template (limited validation). Developers can register their own formats using package "github.com/santhosh-tekuri/jsonschema/formats".

"base64" contentEncoding is supported. Custom decoders can be registered using package "github.com/santhosh-tekuri/jsonschema/decoders".

"application/json" contentMediaType is supported. Custom mediatypes can be registered using package "github.com/santhosh-tekuri/jsonschema/mediatypes".

The ValidationError returned by Validate method contains detailed context to understand why and where the error is.

Index

• Variables
• func DecodeJSON(r io.Reader) (interface{}, error)
• type Compiler
  • func NewCompiler() *Compiler
  • func (c *Compiler) AddResource(url string, r io.Reader) error
  • func (c *Compiler) Compile(url string) (*Schema, error)
  • func (c *Compiler) MustCompile(url string) *Schema
• type Draft
• type InvalidJSONTypeError
  • func (e InvalidJSONTypeError) Error() string
• type Schema
  • func Compile(url string) (*Schema, error)
  • func MustCompile(url string) *Schema
  • func (s *Schema) Validate(r io.Reader) error
  • func (s *Schema) ValidateInterface(doc interface{}) (err error)
• type SchemaError
  • func (se *SchemaError) Error() string
• type ValidationError
  • func (ve *ValidationError) Error() string

Variables

var Draft4 = &Draft{id: "id", version: 4}

Draft4 respresents http://json-schema.org/specification-links.html#draft-4

var Draft6 = &Draft{id: "$id", version: 6}

Draft6 respresents http://json-schema.org/specification-links.html#draft-6

var Draft7 = &Draft{id: "$id", version: 7}

Draft7 respresents http://json-schema.org/specification-links.html#draft-7

Functions

func DecodeJSON

func DecodeJSON(r io.Reader) (interface{}, error)

DecodeJSON decodes json document from r.

Note that number is decoded into json.Number instead of as a float64

Types

type Compiler

type Compiler struct {
	// Draft represents the draft used when '$schema' attribute is missing.
	//
	// This defaults to latest draft (currently draft6).
	Draft *Draft

	// ExtractAnnotations tells whether schema annotations has to be extracted
	// in compiled Schema or not.
	ExtractAnnotations bool
	// contains filtered or unexported fields
}

A Compiler represents a json-schema compiler.

Currently draft4 and draft6 are supported

func NewCompiler

func NewCompiler() *Compiler

NewCompiler returns a draft4 json-schema Compiler object.

func (*Compiler) AddResource

func (c *Compiler) AddResource(url string, r io.Reader) error

AddResource adds in-memory resource to the compiler.

Note that url must not have fragment

func (*Compiler) Compile

func (c *Compiler) Compile(url string) (*Schema, error)

Compile parses json-schema at given url returns, if successful, a Schema object that can be used to match against json.

func (*Compiler) MustCompile

func (c *Compiler) MustCompile(url string) *Schema

MustCompile is like Compile but panics if the url cannot be compiled to *Schema. It simplifies safe initialization of global variables holding compiled Schemas.

type Draft

type Draft struct {
	// contains filtered or unexported fields
}

A Draft represents json-schema draft

type InvalidJSONTypeError

type InvalidJSONTypeError string

InvalidJSONTypeError is the error type returned by ValidateInteface. this tells that specified go object is not valid jsonType.

func (InvalidJSONTypeError) Error

func (e InvalidJSONTypeError) Error() string

type Schema

type Schema struct {
	URL string // absolute url of the resource.
	Ptr string // json-pointer to schema. always starts with `#`.

	// type agnostic validations
	Always   *bool         // always pass/fail. used when booleans are used as schemas in draft-07.
	Ref      *Schema       // reference to actual schema. if not nil, all the remaining fields are ignored.
	Types    []string      // allowed types.
	Constant []interface{} // first element in slice is constant value. note: slice is used to capture nil constant.
	Enum     []interface{} // allowed values.

	Not   *Schema
	AllOf []*Schema
	AnyOf []*Schema
	OneOf []*Schema
	If    *Schema
	Then  *Schema // nil, when If is nil.
	Else  *Schema // nil, when If is nil.

	// object validations
	MinProperties        int      // -1 if not specified.
	MaxProperties        int      // -1 if not specified.
	Required             []string // list of required properties.
	Properties           map[string]*Schema
	PropertyNames        *Schema
	RegexProperties      bool // property names must be valid regex. used only in draft4 as workaround in metaschema.
	PatternProperties    map[*regexp.Regexp]*Schema
	AdditionalProperties interface{}            // nil or false or *Schema.
	Dependencies         map[string]interface{} // value is *Schema or []string.

	// array validations
	MinItems        int // -1 if not specified.
	MaxItems        int // -1 if not specified.
	UniqueItems     bool
	Items           interface{} // nil or *Schema or []*Schema
	AdditionalItems interface{} // nil or bool or *Schema.
	Contains        *Schema

	// string validations
	MinLength        int // -1 if not specified.
	MaxLength        int // -1 if not specified.
	Pattern          *regexp.Regexp
	Format           formats.Format
	FormatName       string
	ContentEncoding  string
	Decoder          decoders.Decoder
	ContentMediaType string
	MediaType        mediatypes.MediaType

	// number validators
	Minimum          *big.Float
	ExclusiveMinimum *big.Float
	Maximum          *big.Float
	ExclusiveMaximum *big.Float
	MultipleOf       *big.Float

	// annotations. captured only when Compiler.ExtractAnnotations is true.
	Title       string
	Description string
	Default     interface{}
	ReadOnly    bool
	WriteOnly   bool
	Examples    []interface{}
	// contains filtered or unexported fields
}

A Schema represents compiled version of json-schema.

func Compile

func Compile(url string) (*Schema, error)

Compile parses json-schema at given url returns, if successful, a Schema object that can be used to match against json.

The json-schema is validated with draft4 specification. Returned error can be *SchemaError

func MustCompile

func MustCompile(url string) *Schema

MustCompile is like Compile but panics if the url cannot be compiled to *Schema. It simplifies safe initialization of global variables holding compiled Schemas.

func (*Schema) Validate

func (s *Schema) Validate(r io.Reader) error

Validate validates the given json data, against the json-schema.

Returned error can be *ValidationError.

func (*Schema) ValidateInterface

func (s *Schema) ValidateInterface(doc interface{}) (err error)

ValidateInterface validates given doc, against the json-schema.

the doc must be the value decoded by json package using interface{} type. we recommend to use jsonschema.DecodeJSON(io.Reader) to decode JSON.

type SchemaError

type SchemaError struct {
	// SchemaURL is the url to json-schema that filed to compile.
	// This is helpful, if your schema refers to external schemas
	SchemaURL string

	// Err is the error that occurred during compilation.
	// It could be ValidationError, because compilation validates
	// given schema against the json meta-schema
	Err error
}

SchemaError is the error type returned by Compile.

func (*SchemaError) Error

func (se *SchemaError) Error() string

type ValidationError

type ValidationError struct {
	// Message describes error
	Message string

	// InstancePtr is json-pointer which refers to json-fragment in json instance
	// that is not valid
	InstancePtr string

	// SchemaURL is the url to json-schema against which validation failed.
	// This is helpful, if your schema refers to external schemas
	SchemaURL string

	// SchemaPtr is json-pointer which refers to json-fragment in json schema
	// that failed to satisfy
	SchemaPtr string

	// Causes details the nested validation errors
	Causes []*ValidationError
}

ValidationError is the error type returned by Validate.

func (*ValidationError) Error

func (ve *ValidationError) Error() string