gojsonschema

package module
v0.0.0-...-ac972c2 Latest Latest
Warning

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

Go to latest
Published: Dec 4, 2016 License: Apache-2.0 Imports: 21 Imported by: 0

README

Build Status

gojsonschema

Description

An implementation of JSON Schema, based on IETF's draft v4 - Go language

References :

Installation

go get github.com/xeipuuv/gojsonschema

Dependencies :

Usage

Example

package main

import (
    "fmt"
    "github.com/xeipuuv/gojsonschema"
)

func main() {

    schemaLoader := gojsonschema.NewReferenceLoader("file:///home/me/schema.json")
    documentLoader := gojsonschema.NewReferenceLoader("file:///home/me/document.json")

    result, err := gojsonschema.Validate(schemaLoader, documentLoader)
    if err != nil {
        panic(err.Error())
    }

    if result.Valid() {
        fmt.Printf("The document is valid\n")
    } else {
        fmt.Printf("The document is not valid. see errors :\n")
        for _, desc := range result.Errors() {
            fmt.Printf("- %s\n", desc)
        }
    }

}


Loaders

There are various ways to load your JSON data. In order to load your schemas and documents, first declare an appropriate loader :

  • Web / HTTP, using a reference :
loader := gojsonschema.NewReferenceLoader("http://www.some_host.com/schema.json")
  • Local file, using a reference :
loader := gojsonschema.NewReferenceLoader("file:///home/me/schema.json")

References use the URI scheme, the prefix (file://) and a full path to the file are required.

  • JSON strings :
loader := gojsonschema.NewStringLoader(`{"type": "string"}`)
  • Custom Go types :
m := map[string]interface{}{"type": "string"}
loader := gojsonschema.NewGoLoader(m)

And

type Root struct {
	Users []User `json:"users"`
}

type User struct {
	Name string `json:"name"`
}

...

data := Root{}
data.Users = append(data.Users, User{"John"})
data.Users = append(data.Users, User{"Sophia"})
data.Users = append(data.Users, User{"Bill"})

loader := gojsonschema.NewGoLoader(data)
Validation

Once the loaders are set, validation is easy :

result, err := gojsonschema.Validate(schemaLoader, documentLoader)

Alternatively, you might want to load a schema only once and process to multiple validations :

schema, err := gojsonschema.NewSchema(schemaLoader)
...
result1, err := schema.Validate(documentLoader1)
...
result2, err := schema.Validate(documentLoader2)
...
// etc ...

To check the result :

    if result.Valid() {
    	fmt.Printf("The document is valid\n")
    } else {
        fmt.Printf("The document is not valid. see errors :\n")
        for _, err := range result.Errors() {
        	// Err implements the ResultError interface
            fmt.Printf("- %s\n", err)
        }
    }

Working with Errors

The library handles string error codes which you can customize by creating your own gojsonschema.locale and setting it

gojsonschema.Locale = YourCustomLocale{}

However, each error contains additional contextual information.

err.Type(): string Returns the "type" of error that occurred. Note you can also type check. See below

Note: An error of RequiredType has an err.Type() return value of "required"

"required": RequiredError
"invalid_type": InvalidTypeError
"number_any_of": NumberAnyOfError
"number_one_of": NumberOneOfError
"number_all_of": NumberAllOfError
"number_not": NumberNotError
"missing_dependency": MissingDependencyError
"internal": InternalError
"enum": EnumError
"array_no_additional_items": ArrayNoAdditionalItemsError
"array_min_items": ArrayMinItemsError
"array_max_items": ArrayMaxItemsError
"unique": ItemsMustBeUniqueError
"array_min_properties": ArrayMinPropertiesError
"array_max_properties": ArrayMaxPropertiesError
"additional_property_not_allowed": AdditionalPropertyNotAllowedError
"invalid_property_pattern": InvalidPropertyPatternError
"string_gte": StringLengthGTEError
"string_lte": StringLengthLTEError
"pattern": DoesNotMatchPatternError
"multiple_of": MultipleOfError
"number_gte": NumberGTEError
"number_gt": NumberGTError
"number_lte": NumberLTEError
"number_lt": NumberLTError

err.Value(): interface{} Returns the value given

err.Context(): gojsonschema.jsonContext Returns the context. This has a String() method that will print something like this: (root).firstName

err.Field(): string Returns the fieldname in the format firstName, or for embedded properties, person.firstName. This returns the same as the String() method on err.Context() but removes the (root). prefix.

err.Description(): string The error description. This is based on the locale you are using. See the beginning of this section for overwriting the locale with a custom implementation.

err.Details(): gojsonschema.ErrorDetails Returns a map[string]interface{} of additional error details specific to the error. For example, GTE errors will have a "min" value, LTE will have a "max" value. See errors.go for a full description of all the error details. Every error always contains a "field" key that holds the value of err.Field()

Note in most cases, the err.Details() will be used to generate replacement strings in your locales. and not used directly i.e.

%field% must be greater than or equal to %min%

Formats

JSON Schema allows for optional "format" property to validate strings against well-known formats. gojsonschema ships with all of the formats defined in the spec that you can use like this:

{"type": "string", "format": "email"}

Available formats: date-time, hostname, email, ipv4, ipv6, uri.

For repetitive or more complex formats, you can create custom format checkers and add them to gojsonschema like this:

// Define the format checker
type RoleFormatChecker struct {}

// Ensure it meets the gojsonschema.FormatChecker interface
func (f RoleFormatChecker) IsFormat(input string) bool {
    return strings.HasPrefix("ROLE_", input)
}

// Add it to the library
gojsonschema.FormatCheckers.Add("role", RoleFormatChecker{})

Now to use in your json schema:

{"type": "string", "format": "role"}

Uses

gojsonschema uses the following test suite :

https://github.com/json-schema/JSON-Schema-Test-Suite

Documentation

Index

Constants

View Source
const (
	STRING_NUMBER                     = "number"
	STRING_ARRAY_OF_STRINGS           = "array of strings"
	STRING_ARRAY_OF_SCHEMAS           = "array of schemas"
	STRING_SCHEMA                     = "schema"
	STRING_SCHEMA_OR_ARRAY_OF_STRINGS = "schema or array of strings"
	STRING_PROPERTIES                 = "properties"
	STRING_DEPENDENCY                 = "dependency"
	STRING_PROPERTY                   = "property"
	STRING_UNDEFINED                  = "undefined"
	STRING_CONTEXT_ROOT               = "(root)"
	STRING_ROOT_SCHEMA_PROPERTY       = "(root)"
)
View Source
const (
	KEY_SCHEMA                = "$subSchema"
	KEY_ID                    = "$id"
	KEY_REF                   = "$ref"
	KEY_TITLE                 = "title"
	KEY_DESCRIPTION           = "description"
	KEY_TYPE                  = "type"
	KEY_ITEMS                 = "items"
	KEY_ADDITIONAL_ITEMS      = "additionalItems"
	KEY_PROPERTIES            = "properties"
	KEY_PATTERN_PROPERTIES    = "patternProperties"
	KEY_ADDITIONAL_PROPERTIES = "additionalProperties"
	KEY_DEFINITIONS           = "definitions"
	KEY_MULTIPLE_OF           = "multipleOf"
	KEY_MINIMUM               = "minimum"
	KEY_MAXIMUM               = "maximum"
	KEY_EXCLUSIVE_MINIMUM     = "exclusiveMinimum"
	KEY_EXCLUSIVE_MAXIMUM     = "exclusiveMaximum"
	KEY_MIN_LENGTH            = "minLength"
	KEY_MAX_LENGTH            = "maxLength"
	KEY_PATTERN               = "pattern"
	KEY_FORMAT                = "format"
	KEY_MIN_PROPERTIES        = "minProperties"
	KEY_MAX_PROPERTIES        = "maxProperties"
	KEY_DEPENDENCIES          = "dependencies"
	KEY_REQUIRED              = "required"
	KEY_MIN_ITEMS             = "minItems"
	KEY_MAX_ITEMS             = "maxItems"
	KEY_UNIQUE_ITEMS          = "uniqueItems"
	KEY_ENUM                  = "enum"
	KEY_ONE_OF                = "oneOf"
	KEY_ANY_OF                = "anyOf"
	KEY_ALL_OF                = "allOf"
	KEY_NOT                   = "not"
	KEY_MESSAGES              = "messages"
)
View Source
const (
	TYPE_ARRAY   = `array`
	TYPE_BOOLEAN = `boolean`
	TYPE_INTEGER = `integer`
	TYPE_NUMBER  = `number`
	TYPE_NULL    = `null`
	TYPE_OBJECT  = `object`
	TYPE_STRING  = `string`
)

Variables

View Source
var (
	// Formatters holds the valid formatters, and is a public variable
	// so library users can add custom formatters
	FormatCheckers = FormatCheckerChain{
		// contains filtered or unexported fields
	}
)
View Source
var JSON_TYPES []string
View Source
var (
	// Locale is the default locale to use
	// Library users can overwrite with their own implementation
	Locale locale = DefaultLocale{}
)
View Source
var SCHEMA_TYPES []string

Functions

func NewGoLoader

func NewGoLoader(source interface{}) *jsonGoLoader

func NewReferenceLoader

func NewReferenceLoader(source string) *jsonReferenceLoader

NewReferenceLoader returns a JSON reference loader using the given source and the local OS file system.

func NewReferenceLoaderFileSystem

func NewReferenceLoaderFileSystem(source string, fs http.FileSystem) *jsonReferenceLoader

NewReferenceLoaderFileSystem returns a JSON reference loader using the given source and file system.

func NewStringLoader

func NewStringLoader(source string) *jsonStringLoader

Types

type AdditionalPropertyNotAllowedError

type AdditionalPropertyNotAllowedError struct {
	ResultErrorFields
}

AdditionalPropertyNotAllowedError. ErrorDetails: property

type ArrayMaxItemsError

type ArrayMaxItemsError struct {
	ResultErrorFields
}

ArrayMaxItemsError. ErrorDetails: max

type ArrayMaxPropertiesError

type ArrayMaxPropertiesError struct {
	ResultErrorFields
}

ArrayMaxPropertiesError. ErrorDetails: max

type ArrayMinItemsError

type ArrayMinItemsError struct {
	ResultErrorFields
}

ArrayMinItemsError. ErrorDetails: min

type ArrayMinPropertiesError

type ArrayMinPropertiesError struct {
	ResultErrorFields
}

ArrayMinPropertiesError. ErrorDetails: min

type ArrayNoAdditionalItemsError

type ArrayNoAdditionalItemsError struct {
	ResultErrorFields
}

ArrayNoAdditionalItemsError. ErrorDetails: -

type DateTimeFormatChecker

type DateTimeFormatChecker struct{}

DateTimeFormatChecker verifies date/time formats per RFC3339 5.6

Valid formats:

	Partial Time: HH:MM:SS
	Full Date: YYYY-MM-DD
	Full Time: HH:MM:SSZ-07:00
	Date Time: YYYY-MM-DDTHH:MM:SSZ-0700

Where
	YYYY = 4DIGIT year
	MM = 2DIGIT month ; 01-12
	DD = 2DIGIT day-month ; 01-28, 01-29, 01-30, 01-31 based on month/year
	HH = 2DIGIT hour ; 00-23
	MM = 2DIGIT ; 00-59
	SS = 2DIGIT ; 00-58, 00-60 based on leap second rules
	T = Literal
	Z = Literal

Note: Nanoseconds are also suported in all formats

http://tools.ietf.org/html/rfc3339#section-5.6

func (DateTimeFormatChecker) IsFormat

func (f DateTimeFormatChecker) IsFormat(input string) bool

type DefaultJSONLoaderFactory

type DefaultJSONLoaderFactory struct {
}

func (DefaultJSONLoaderFactory) New

type DefaultLocale

type DefaultLocale struct{}

DefaultLocale is the default locale for this package

func (DefaultLocale) AdditionalPropertyNotAllowed

func (l DefaultLocale) AdditionalPropertyNotAllowed() string

func (DefaultLocale) ArrayMaxItems

func (l DefaultLocale) ArrayMaxItems() string

func (DefaultLocale) ArrayMaxProperties

func (l DefaultLocale) ArrayMaxProperties() string

func (DefaultLocale) ArrayMinItems

func (l DefaultLocale) ArrayMinItems() string

func (DefaultLocale) ArrayMinProperties

func (l DefaultLocale) ArrayMinProperties() string

func (DefaultLocale) ArrayNoAdditionalItems

func (l DefaultLocale) ArrayNoAdditionalItems() string

func (DefaultLocale) ArrayNotEnoughItems

func (l DefaultLocale) ArrayNotEnoughItems() string

func (DefaultLocale) CannotBeGT

func (l DefaultLocale) CannotBeGT() string

func (DefaultLocale) CannotBeUsedWithout

func (l DefaultLocale) CannotBeUsedWithout() string

func (DefaultLocale) DoesNotMatchFormat

func (l DefaultLocale) DoesNotMatchFormat() string

func (DefaultLocale) DoesNotMatchPattern

func (l DefaultLocale) DoesNotMatchPattern() string

func (DefaultLocale) Duplicated

func (l DefaultLocale) Duplicated() string

func (DefaultLocale) Enum

func (l DefaultLocale) Enum() string

func (DefaultLocale) ErrorFormat

func (l DefaultLocale) ErrorFormat() string

Replacement options: field, description, context, value

func (DefaultLocale) GreaterThanZero

func (l DefaultLocale) GreaterThanZero() string

func (DefaultLocale) Internal

func (l DefaultLocale) Internal() string

func (DefaultLocale) InvalidPropertyPattern

func (l DefaultLocale) InvalidPropertyPattern() string

func (DefaultLocale) InvalidType

func (l DefaultLocale) InvalidType() string

func (DefaultLocale) KeyCannotBeGreaterThan

func (l DefaultLocale) KeyCannotBeGreaterThan() string

func (DefaultLocale) KeyItemsMustBeOfType

func (l DefaultLocale) KeyItemsMustBeOfType() string

func (DefaultLocale) KeyItemsMustBeUnique

func (l DefaultLocale) KeyItemsMustBeUnique() string

func (DefaultLocale) MissingDependency

func (l DefaultLocale) MissingDependency() string

func (DefaultLocale) MultipleOf

func (l DefaultLocale) MultipleOf() string

func (DefaultLocale) MustBeGTEZero

func (l DefaultLocale) MustBeGTEZero() string

func (DefaultLocale) MustBeOfA

func (l DefaultLocale) MustBeOfA() string

func (DefaultLocale) MustBeOfAn

func (l DefaultLocale) MustBeOfAn() string

func (DefaultLocale) MustBeOfType

func (l DefaultLocale) MustBeOfType() string

func (DefaultLocale) MustBeValidFormat

func (l DefaultLocale) MustBeValidFormat() string

func (DefaultLocale) MustBeValidRegex

func (l DefaultLocale) MustBeValidRegex() string

func (DefaultLocale) NotAValidType

func (l DefaultLocale) NotAValidType() string

func (DefaultLocale) NumberAllOf

func (l DefaultLocale) NumberAllOf() string

func (DefaultLocale) NumberAnyOf

func (l DefaultLocale) NumberAnyOf() string

func (DefaultLocale) NumberGT

func (l DefaultLocale) NumberGT() string

func (DefaultLocale) NumberGTE

func (l DefaultLocale) NumberGTE() string

func (DefaultLocale) NumberLT

func (l DefaultLocale) NumberLT() string

func (DefaultLocale) NumberLTE

func (l DefaultLocale) NumberLTE() string

func (DefaultLocale) NumberNot

func (l DefaultLocale) NumberNot() string

func (DefaultLocale) NumberOneOf

func (l DefaultLocale) NumberOneOf() string

func (DefaultLocale) ReferenceMustBeCanonical

func (l DefaultLocale) ReferenceMustBeCanonical() string

func (DefaultLocale) RegexPattern

func (l DefaultLocale) RegexPattern() string

Schema validators

func (DefaultLocale) Required

func (l DefaultLocale) Required() string

func (DefaultLocale) StringGTE

func (l DefaultLocale) StringGTE() string

func (DefaultLocale) StringLTE

func (l DefaultLocale) StringLTE() string

func (DefaultLocale) Unique

func (l DefaultLocale) Unique() string

type DoesNotMatchFormatError

type DoesNotMatchFormatError struct {
	ResultErrorFields
}

DoesNotMatchFormatError. ErrorDetails: format

type DoesNotMatchPatternError

type DoesNotMatchPatternError struct {
	ResultErrorFields
}

DoesNotMatchPatternError. ErrorDetails: pattern

type EmailFormatChecker

type EmailFormatChecker struct{}

EmailFormatter verifies email address formats

func (EmailFormatChecker) IsFormat

func (f EmailFormatChecker) IsFormat(input string) bool

type EnumError

type EnumError struct {
	ResultErrorFields
}

EnumError. ErrorDetails: allowed

type ErrorDetails

type ErrorDetails map[string]interface{}

ErrorDetails is a map of details specific to each error. While the values will vary, every error will contain a "field" value

type FileSystemJSONLoaderFactory

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

func (FileSystemJSONLoaderFactory) New

type FormatChecker

type FormatChecker interface {
	IsFormat(input string) bool
}

FormatChecker is the interface all formatters added to FormatCheckerChain must implement

type FormatCheckerChain

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

FormatCheckerChain holds the formatters

func (*FormatCheckerChain) Add

Add adds a FormatChecker to the FormatCheckerChain The name used will be the value used for the format key in your json schema

func (*FormatCheckerChain) Has

func (c *FormatCheckerChain) Has(name string) bool

Has checks to see if the FormatCheckerChain holds a FormatChecker with the given name

func (*FormatCheckerChain) IsFormat

func (c *FormatCheckerChain) IsFormat(name string, input interface{}) bool

IsFormat will check an input against a FormatChecker with the given name to see if it is the correct format

func (*FormatCheckerChain) Remove

func (c *FormatCheckerChain) Remove(name string) *FormatCheckerChain

Remove deletes a FormatChecker from the FormatCheckerChain (if it exists)

type HostnameFormatChecker

type HostnameFormatChecker struct{}

HostnameFormatChecker validates a hostname is in the correct format

func (HostnameFormatChecker) IsFormat

func (f HostnameFormatChecker) IsFormat(input string) bool

type IPV4FormatChecker

type IPV4FormatChecker struct{}

IPV4FormatChecker verifies IP addresses in the ipv4 format

func (IPV4FormatChecker) IsFormat

func (f IPV4FormatChecker) IsFormat(input string) bool

Credit: https://github.com/asaskevich/govalidator

type IPV6FormatChecker

type IPV6FormatChecker struct{}

IPV6FormatChecker verifies IP addresses in the ipv6 format

func (IPV6FormatChecker) IsFormat

func (f IPV6FormatChecker) IsFormat(input string) bool

Credit: https://github.com/asaskevich/govalidator

type InternalError

type InternalError struct {
	ResultErrorFields
}

InternalError. ErrorDetails: error

type InvalidPropertyPatternError

type InvalidPropertyPatternError struct {
	ResultErrorFields
}

InvalidPropertyPatternError. ErrorDetails: property, pattern

type InvalidTypeError

type InvalidTypeError struct {
	ResultErrorFields
}

InvalidTypeError. ErrorDetails: expected, given

type ItemsMustBeUniqueError

type ItemsMustBeUniqueError struct {
	ResultErrorFields
}

ItemsMustBeUniqueError. ErrorDetails: type

type JSONLoader

type JSONLoader interface {
	JsonSource() interface{}
	LoadJSON() (interface{}, error)
	JsonReference() (gojsonreference.JsonReference, error)
	LoaderFactory() JSONLoaderFactory
}

type JSONLoaderFactory

type JSONLoaderFactory interface {
	New(source string) JSONLoader
}

type MissingDependencyError

type MissingDependencyError struct {
	ResultErrorFields
}

MissingDependencyError. ErrorDetails: dependency

type MultipleOfError

type MultipleOfError struct {
	ResultErrorFields
}

MultipleOfError. ErrorDetails: multiple

type NumberAllOfError

type NumberAllOfError struct {
	ResultErrorFields
}

NumberAllOfError. ErrorDetails: -

type NumberAnyOfError

type NumberAnyOfError struct {
	ResultErrorFields
}

NumberAnyOfError. ErrorDetails: -

type NumberGTEError

type NumberGTEError struct {
	ResultErrorFields
}

NumberGTEError. ErrorDetails: min

type NumberGTError

type NumberGTError struct {
	ResultErrorFields
}

NumberGTError. ErrorDetails: min

type NumberLTEError

type NumberLTEError struct {
	ResultErrorFields
}

NumberLTEError. ErrorDetails: max

type NumberLTError

type NumberLTError struct {
	ResultErrorFields
}

NumberLTError. ErrorDetails: max

type NumberNotError

type NumberNotError struct {
	ResultErrorFields
}

NumberNotError. ErrorDetails: -

type NumberOneOfError

type NumberOneOfError struct {
	ResultErrorFields
}

NumberOneOfError. ErrorDetails: -

type RegexFormatChecker

type RegexFormatChecker struct{}

RegexFormatChecker validates a regex is in the correct format

func (RegexFormatChecker) IsFormat

func (f RegexFormatChecker) IsFormat(input string) bool

IsFormat implements FormatChecker interface.

type RequiredError

type RequiredError struct {
	ResultErrorFields
}

RequiredError. ErrorDetails: property string

type Result

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

func Validate

func Validate(ls JSONLoader, ld JSONLoader) (*Result, error)

func (*Result) Errors

func (v *Result) Errors() []ResultError

func (*Result) Valid

func (v *Result) Valid() bool

type ResultError

type ResultError interface {
	Field() string
	SetType(string)
	Type() string
	SetContext(*jsonContext)
	Context() *jsonContext
	SetDescription(string)
	Description() string
	SetValue(interface{})
	Value() interface{}
	SetDetails(ErrorDetails)
	Details() ErrorDetails
}

ResultError is the interface that library errors must implement

type ResultErrorFields

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

ResultErrorFields holds the fields for each ResultError implementation. ResultErrorFields implements the ResultError interface, so custom errors can be defined by just embedding this type

func (*ResultErrorFields) Context

func (v *ResultErrorFields) Context() *jsonContext

func (*ResultErrorFields) Description

func (v *ResultErrorFields) Description() string

func (*ResultErrorFields) Details

func (v *ResultErrorFields) Details() ErrorDetails

func (*ResultErrorFields) Field

func (v *ResultErrorFields) Field() string

Field outputs the field name without the root context i.e. firstName or person.firstName instead of (root).firstName or (root).person.firstName

func (*ResultErrorFields) SetContext

func (v *ResultErrorFields) SetContext(context *jsonContext)

func (*ResultErrorFields) SetDescription

func (v *ResultErrorFields) SetDescription(description string)

func (*ResultErrorFields) SetDetails

func (v *ResultErrorFields) SetDetails(details ErrorDetails)

func (*ResultErrorFields) SetType

func (v *ResultErrorFields) SetType(errorType string)

func (*ResultErrorFields) SetValue

func (v *ResultErrorFields) SetValue(value interface{})

func (ResultErrorFields) String

func (v ResultErrorFields) String() string

func (*ResultErrorFields) Type

func (v *ResultErrorFields) Type() string

func (*ResultErrorFields) Value

func (v *ResultErrorFields) Value() interface{}

type Schema

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

func NewSchema

func NewSchema(l JSONLoader) (*Schema, error)

func (*Schema) SetRootSchemaName

func (d *Schema) SetRootSchemaName(name string)

func (*Schema) Validate

func (v *Schema) Validate(l JSONLoader) (*Result, error)

type StringLengthGTEError

type StringLengthGTEError struct {
	ResultErrorFields
}

StringLengthGTEError. ErrorDetails: min

type StringLengthLTEError

type StringLengthLTEError struct {
	ResultErrorFields
}

StringLengthLTEError. ErrorDetails: max

type URIFormatChecker

type URIFormatChecker struct{}

URIFormatCheckers validates a URI with a valid Scheme per RFC3986

func (URIFormatChecker) IsFormat

func (f URIFormatChecker) IsFormat(input string) bool

type UUIDFormatChecker

type UUIDFormatChecker struct{}

UUIDFormatChecker validates a UUID is in the correct format

func (UUIDFormatChecker) IsFormat

func (f UUIDFormatChecker) IsFormat(input string) bool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL