jsonschema

package module
v4.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2021 License: BSD-3-Clause Imports: 18 Imported by: 0

README

jsonschema v4.0.0

License GoDoc Go Report Card Build Status codecov.io

Package jsonschema provides json-schema compilation and validation.

Features:
  • implements draft 2019-09, draft-7, draft-6, draft-4
  • fully compliant with JSON-Schema-Test-Suite, (excluding some optional)
    • list of optioanl tests that are excluded can be found in schema_test.go(variable skipTests)
  • validates schemas against meta-schema
  • full support of remote references
  • support of recursive references between schemas
  • detects infinite loop in schemas
  • thread safe validation
  • rich, intutive hierarchial error messages with json-pointers to exact location
  • supports enabling format and content Assertions in draft2019-09
    • make Compiler.AssertFormat, Compiler.AssertContent true
  • compiled schema can be introspected. easier to develop tools like generating go structs given schema
  • supports user-defined keywords via extensions
  • implements following formats (supports user-defined)
    • date-time, date, time, duration
    • uuid, hostname, email
    • ip-address, ipv4, ipv6
    • uri, uriref, uri-template(limited validation)
    • json-pointer, relative-json-pointer
    • regex, format
  • implements following contentEncoding (supports user-defined)
    • base64
  • implements following contentMediaType (supports user-defined)
    • application/json
  • can load from files/http/https/string/[]byte/io.Reader (suports user-defined)

see examples in godoc

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 specific version, 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/v4/httploader"

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 [-draft INT] <schema-file> [<json-doc>]...

if no <json-doc> arguments are passed, it simply validates the <schema-file>.
if $schema attribute is missing in schema, it uses draft7. this can be overriden by passing -draft flag

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

Validating YAML Document

since yaml supports non-string keys, such yaml documents are rendered as invalid json documents.
yaml parser returns map[interface{}]interface{} for object, whereas json parser returns map[string]interafce{}.
this package accepts only map[string]interface{}, so we need to manually convert them to map[string]interface{}

https://play.golang.org/p/sJy1qY7dXgA

the above example shows how to validate yaml document with jsonschema.
the convertion explained above is implemented by toStringKeys function

Documentation

Overview

Package jsonschema provides json-schema compilation and validation.

Features:

  • implements draft 2019-09, draft-7, draft-6, draft-4
  • fully compliant with JSON-Schema-Test-Suite, (excluding some optional)
  • list of optioanl tests that are excluded can be found in schema_test.go(variable skipTests)
  • validates schemas against meta-schema
  • full support of remote references
  • support of recursive references between schemas
  • detects infinite loop in schemas
  • thread safe validation
  • rich, intutive hierarchial error messages with json-pointers to exact location
  • supports enabling format and content Assertions in draft2019-09
  • make Compiler.AssertFormat, Compiler.AssertContent true
  • compiled schema can be introspected. easier to develop tools like generating go structs given schema
  • supports user-defined keywords via extensions
  • implements following formats (supports user-defined)
  • date-time, date, time, duration
  • uuid, hostname, email
  • ip-address, ipv4, ipv6
  • uri, uriref, uri-template(limited validation)
  • json-pointer, relative-json-pointer
  • regex, format
  • implements following contentEncoding (supports user-defined)
  • base64
  • implements following contentMediaType (supports user-defined)
  • application/json
  • can load from files/http/https/string/[]byte/io.Reader (suports user-defined)

The schema is compiled against the version specified in "$schema" property. If "$schema" property is missing, it uses latest draft which currently implemented by this library.

You can force to use specific draft, 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/v4/httploader"

you can validate yaml documents. see https://play.golang.org/p/sJy1qY7dXgA

Example 
sch, err := jsonschema.Compile("testdata/person_schema.json")
if err != nil {
	log.Fatalf("%#v", err)
}

f, err := os.Open("testdata/person.json")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

if err = sch.Validate(f); err != nil {
	log.Fatalf("%#v", err)
}

Output:
Example (Extension) 
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"strconv"
	"strings"

	"github.com/santhosh-tekuri/jsonschema/v4"
)

var powerOfMeta = jsonschema.MustCompileString("powerOf.json", `{
	"properties" : {
		"powerOf": {
			"type": "integer",
			"exclusiveMinimum": 0
		}
	}
}`)

type powerOfCompiler struct{}

func (powerOfCompiler) Compile(ctx jsonschema.CompilerContext, m map[string]interface{}) (jsonschema.ExtSchema, error) {
	if pow, ok := m["powerOf"]; ok {
		n, err := pow.(json.Number).Int64()
		return powerOfSchema(n), err
	}

	// nothing to compile, return nil
	return nil, nil
}

type powerOfSchema int64

func (s powerOfSchema) Validate(ctx jsonschema.ValidationContext, v interface{}) error {
	switch v.(type) {
	case json.Number, float64, int, int32, int64:
		pow := int64(s)
		n, _ := strconv.ParseInt(fmt.Sprint(v), 10, 64)
		for n%pow == 0 {
			n = n / pow
		}
		if n != 1 {
			return ctx.Error("powerOf", "%v not powerOf %v", v, pow)
		}
		return nil
	default:
		return nil
	}
}

func main() {
	c := jsonschema.NewCompiler()
	c.RegisterExtension("powerOf", powerOfMeta, powerOfCompiler{})

	schema := `{"powerOf": 10}`
	instance := `100`

	if err := c.AddResource("schema.json", strings.NewReader(schema)); err != nil {
		log.Fatal(err)
	}
	sch, err := c.Compile("schema.json")
	if err != nil {
		log.Fatalf("%#v", err)
	}

	if err = sch.Validate(strings.NewReader(instance)); err != nil {
		log.Fatalf("%#v", err)
	}
}

Output:
Example (FromString)

Example_fromString shows how to load schema from string. 

schema := `{"type": "object"}`
instance := `{"foo": "bar"}`

sch, err := jsonschema.CompileString("schema.json", schema)
if err != nil {
	log.Fatalf("%#v", err)
}

if err = sch.Validate(strings.NewReader(instance)); err != nil {
	log.Fatalf("%#v", err)
}

Output:
Example (FromStrings)

Example_fromStrings shows how to load schema from more than one string. 

c := jsonschema.NewCompiler()
if err := c.AddResource("main.json", strings.NewReader(`{"$ref":"obj.json"}`)); err != nil {
	log.Fatal(err)
}
if err := c.AddResource("obj.json", strings.NewReader(`{"type":"object"}`)); err != nil {
	log.Fatal(err)
}
sch, err := c.Compile("main.json")
if err != nil {
	log.Fatalf("%#v", err)
}

if err = sch.Validate(strings.NewReader(`{}`)); err != nil {
	log.Fatalf("%#v", err)
}

Output:
Example (UserDefinedContent)

Example_userDefinedContent shows how to define "hex" contentEncoding and "application/xml" contentMediaType 

jsonschema.Decoders["hex"] = hex.DecodeString
jsonschema.MediaTypes["application/xml"] = func(b []byte) error {
	return xml.Unmarshal(b, new(interface{}))
}

schema := `{
		"$schema": "http://json-schema.org/draft-07/schema",
		"type": "object",
		"properties": {
			"xml" : {
				"type": "string",
				"contentEncoding": "hex",
				"contentMediaType": "application/xml"
			}
		}
	}`
instance := `{"xml": "3c726f6f742f3e"}`

sch, err := jsonschema.CompileString("schema.json", schema)
if err != nil {
	log.Fatalf("%#v", err)
}

if err = sch.Validate(strings.NewReader(instance)); err != nil {
	log.Fatalf("%#v", err)
}

Output:
Example (UserDefinedFormat)

Example_userDefinedFormat shows how to define 'odd-number' format. 

jsonschema.Formats["odd-number"] = func(v interface{}) bool {
	switch v := v.(type) {
	case json.Number, float64, int, int32, int64:
		n, _ := strconv.ParseInt(fmt.Sprint(v), 10, 64)
		return n%2 != 0
	default:
		return true
	}
}

schema := `{
		"$schema": "http://json-schema.org/draft-07/schema",
		"type": "integer",
		"format": "odd-number"
	}`
instance := `5`

sch, err := jsonschema.CompileString("schema.json", schema)
if err != nil {
	log.Fatalf("%#v", err)
}

if err = sch.Validate(strings.NewReader(instance)); err != nil {
	log.Fatalf("%#v", err)
}

Output:
Example (UserDefinedLoader)

Example_userDefinedLoader shows how to define custom schema loader.

we are implementing a "map" protocol which servers schemas from go map variable. 

var schemas = map[string]string{
	"main.json": `{"$ref":"obj.json"}`,
	"obj.json":  `{"type":"object"}`,
}
jsonschema.Loaders["map"] = func(url string) (io.ReadCloser, error) {
	schema, ok := schemas[strings.TrimPrefix(url, "map:///")]
	if !ok {
		return nil, fmt.Errorf("%q not found", url)
	}
	return io.NopCloser(strings.NewReader(schema)), nil
}

sch, err := jsonschema.Compile("map:///main.json")
if err != nil {
	log.Fatalf("%+v", err)
}

if err = sch.Validate(strings.NewReader(`{}`)); err != nil {
	log.Fatalf("%#v", err)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var Decoders = map[string]func(string) ([]byte, error){
	"base64": base64.StdEncoding.DecodeString,
}

Decoders is a registry of functions, which know how to decode string encoded in specific format.

New Decoders can be registered by adding to this map. Key is encoding name, value is function that knows how to decode string in that format.

View Source 
var Draft2019 = &Draft{id: "$id", version: 2019}

Draft2019 respresents https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8

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

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

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

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

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

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

View Source 
var Formats = map[string]func(interface{}) bool{
	"date-time":             isDateTime,
	"date":                  isDate,
	"time":                  isTime,
	"duration":              isDuration,
	"hostname":              isHostname,
	"email":                 isEmail,
	"ip-address":            isIPV4,
	"ipv4":                  isIPV4,
	"ipv6":                  isIPV6,
	"uri":                   isURI,
	"iri":                   isURI,
	"uri-reference":         isURIReference,
	"uriref":                isURIReference,
	"iri-reference":         isURIReference,
	"uri-template":          isURITemplate,
	"regex":                 isRegex,
	"json-pointer":          isJSONPointer,
	"relative-json-pointer": isRelativeJSONPointer,
	"uuid":                  isUUID,
}

Formats is a registry of functions, which know how to validate a specific format.

New Formats can be registered by adding to this map. Key is format name, value is function that knows how to validate that format.

View Source 
var LoadURL = func(s string) (io.ReadCloser, error) {
	u, err := url.Parse(s)
	if err != nil {
		return nil, err
	}
	loader, ok := Loaders[u.Scheme]
	if !ok {
		return nil, SchemeNotRegisteredError(u.Scheme)

	}
	return loader(s)
}

LoadURL loads document at given URL. The default implementation uses Loaders registry to lookup by schema and uses that loader.

Users can change this variable, if they would like to take complete responsibility of loading given URL. Used by Compiler if its LoadURL field is nil.

View Source 
var Loaders = map[string]func(url string) (io.ReadCloser, error){
	"":     loadFile,
	"file": loadFileURL,
}

Loaders is a registry of functions, which know how to load url of specific schema.

New loaders can be registered by adding to this map. Key is schema, value is function that knows how to load url of that schema

View Source 
var MediaTypes = map[string]func([]byte) error{
	"application/json": validateJSON,
}

MediaTypes is a registry of functions, which know how to validate whether the bytes represent data of that mediaType.

New mediaTypes can be registered by adding to this map. Key is mediaType name, value is function that knows how to validate that mediaType.

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 draft2019-09).
	Draft *Draft

	// ExtractAnnotations tells whether schema annotations has to be extracted
	// in compiled Schema or not.
	ExtractAnnotations bool

	// LoadURL loads the document at given URL.
	//
	// If nil, package global LoadURL is used.
	LoadURL func(s string) (io.ReadCloser, error)

	// AssertFormat for specifications >= draft2019-09.
	AssertFormat bool

	// AssertContent for specifications >= draft2019-09.
	AssertContent bool
	// contains filtered or unexported fields
}

A Compiler represents a json-schema compiler.

Currently draft4, draft6 and draft7 are supported

func NewCompiler 

func NewCompiler() *Compiler

NewCompiler returns a json-schema Compiler object. if '$schema' attribute is missing, it is treated as draft7. to change this behavior change Compiler.Draft value

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.

error returned will be of type *SchemaError

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.

func (*Compiler) RegisterExtension 

func (c *Compiler) RegisterExtension(name string, meta *Schema, ext ExtCompiler)

RegisterExtension registers custom keyword(s) into this compiler.

name is extension name, used only to avoid name collisions. meta captures the metaschema for the new keywords. This is used to validate the schema before calling ext.Compile.

type CompilerContext 

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

CompilerContext provides additional context required in compiling for extension.

func (CompilerContext) Compile 

func (ctx CompilerContext) Compile(v interface{}, vPtr string, applicableOnSameInstance bool) (*Schema, error)

Compile compiles given value v into *Schema. This is useful in implementing keyword like allOf/oneOf.

vPtr is the jsonpointer to v.

applicableOnSameInstance tells whether current schema and the given schema v are applied on same instance value. this is used to detect infinite loop in schema.

func (CompilerContext) CompileRef 

func (ctx CompilerContext) CompileRef(ref string, refPtr string, applicableOnSameInstance bool) (*Schema, error)

CompileRef compiles the schema referenced by ref uri

refPtr is the jsonpointer to ref.

applicableOnSameInstance tells whether current schema and the given schema v are applied on same instance value. this is used to detect infinite loop in schema.

type Draft 

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

A Draft represents json-schema draft

type ExtCompiler 

type ExtCompiler interface {
	// Compile compiles the schema m and returns its compiled representation.
	// if the schema m does not contain the keywords defined by this extension,
	// compiled representation nil should be returned.
	Compile(ctx CompilerContext, m map[string]interface{}) (ExtSchema, error)
}

ExtCompiler compiles custom keyword(s) into ExtSchema.

type ExtSchema 

type ExtSchema interface {
	// Validate validates the json value v with this ExtSchema.
	// Returned error must be *ValidationError.
	Validate(ctx ValidationContext, v interface{}) error
}

ExtSchema is schema representation of custom keyword(s)

type InfiniteLoopError 

type InfiniteLoopError string

InfiniteLoopError is returned by Compile. this gives keywordLocation that lead to infinity loop.

func (InfiniteLoopError) Error 

func (e InfiniteLoopError) Error() string

type InvalidJSONTypeError 

type InvalidJSONTypeError string

InvalidJSONTypeError is the error type returned by ValidateInterface. 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 `#`.

	Format          string
	Always          *bool   // always pass/fail. used when booleans are used as schemas in draft-07.
	Ref             *Schema // reference to actual schema.
	RecursiveAnchor bool
	RecursiveRef    *Schema       // reference to actual schema.
	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 bool or *Schema.
	Dependencies          map[string]interface{} // value is *Schema or []string.
	DependentRequired     map[string][]string
	DependentSchemas      map[string]*Schema
	UnevaluatedProperties *Schema

	// 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
	MinContains      int // 1 if not specified
	MaxContains      int // -1 if not specified
	UnevaluatedItems *Schema

	// string validations
	MinLength       int // -1 if not specified.
	MaxLength       int // -1 if not specified.
	Pattern         *regexp.Regexp
	ContentEncoding string

	ContentMediaType string

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

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

	// user defined extensions
	Extensions map[string]ExtSchema
	// 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.

Returned error can be *SchemaError

func CompileString 

func CompileString(url, schema string) (*Schema, error)

CompileString parses and compiles the given schema with given base url.

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 MustCompileString 

func MustCompileString(url, schema string) *Schema

MustCompileString is like CompileString but panics on error. It simplified safe initialization of global variables holding compiled Schema.

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

func (*SchemaError) GoString 

func (se *SchemaError) GoString() string

type SchemeNotRegisteredError 

type SchemeNotRegisteredError string

SchemeNotRegisteredError is the error type returned by Load function. It tells that no Loader is registered for that URL Scheme.

func (SchemeNotRegisteredError) Error 

func (s SchemeNotRegisteredError) Error() string

type ValidationContext 

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

ValidationContext provides additional context required in validating for extension.

func (ValidationContext) Error 

func (ValidationContext) Error(schemaPtr string, format string, a ...interface{}) *ValidationError

Error used to construct validation error by extensions. schemaPtr is relative json pointer.

func (ValidationContext) Validate 

func (ctx ValidationContext) Validate(s *Schema, v interface{}) error

Validate validates schema s with value v. Extension must use this method instead of *Schema.ValidateInterface method. This will be useful in implementing keywords like allOf/oneOf

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

func (*ValidationError) GoString 

func (ve *ValidationError) GoString() string

func (ValidationError) Group 

func (ValidationError) Group(parent *ValidationError, causes ...error) error

Group is used by extensions to group multiple errors as causes to parent error. This is useful in implementing keywords like allOf where each schema specified in allOf can result a validationError.

func (*ValidationError) MessageFmt deprecated 

func (ve *ValidationError) MessageFmt() string

MessageFmt returns the Message formatted, but does not include child Cause messages.

Deprecated: use Error method

Source Files

View all Source files

Directories

Path Synopsis
cmd
jv
Package httploader implements loader.Loader for http/https url.
 Package httploader implements loader.Loader for http/https url.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.