jsonschema

README

jsonschema

Package jsonschema provides json-schema compilation and validation.

This implementation of JSON Schema, supports draft4 and draft6.

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 draft6. 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
• hostname
• email
• ip-address
• ipv4
• ipv6
• uri
• uriref/uri-reference
• regex
• format
• json-pointer
• uri-template (limited validation)

Developers can define their own formats using package jsonschema/formats.

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 and draft6. 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 draft6. 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, hostname, email, ip-address, ipv4, ipv6, uri, uriref, regex, format, json-pointer, uri-template (limited validation).

Developers can define their own formats using package jsonschema/formats.

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 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{}) error
• type SchemaError
  • func (se *SchemaError) Error() string
• type ValidationError
  • func (ve *ValidationError) Error() string

Variables

var Draft4 = &Draft{id: "id"}

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

var Draft6 = &Draft{id: "$id"}

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

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
	// 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 Schema

type Schema struct {
	// 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{}) 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