jsonschema

package module
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2022 License: MIT Imports: 21 Imported by: 0

README

Go Reference

go-jsonschema

Go JSON Schema parser and validator

Although go-jsonschema hasn't reached version 1.0, it already passes all mandatory tests and most optional tests in the test suites for Draft 4, Draft 6 and Draft 7.
A lot of work has already been done to parse a lot of draft2019-09 and draft2020-12 tests.

Errors are not very informative.
E.g. line number, keys, values, etc. aren't reported back.
The main focus has been on speed and correctness of validation, but error reporting should get better over time.

Until the release of version 1.0, breaking changes can happen, but will be avoided if possible.

Usage

It is now possible to marshal and unmarshal schemas directly with encoding/json.

Validate JSON Schema
import "github.com/flowstack/go-jsonschema"

func main() {
    schema := `{"properties": {"id": {"type": "string"}}}`

    // Validate a JSON Schema
    _, err := jsonschema.Validate(schema)
    if err != nil {
        log.Fatal(err)
    }
}
Validate JSON against a JSON Schema
import "github.com/flowstack/go-jsonschema"

func main() {
    schema := `{"properties": {"id": {"type": "string"}}}`

    // Create a validator
    validator, err := jsonschema.NewFromString(schema)
    // Alternative: validator, err := jsonschema.New([]byte(schema))
    if err != nil {
        log.Fatal(err)
    }

    // Validate a JSON document against the schema
    json := `{"id": "123abc"}`
    _, err = validator.Validate([]byte(json))
    if err != nil {
        log.Fatal(err)
    }
}
Marshal / Unmarshal
import "github.com/flowstack/go-jsonschema"

func main() {
    schemaStr := `{"properties": {"id": {"type": "string"}}}`

    // Unmarshal from string to Schema struct
	schema := &jsonschema.Schema{}
	err := json.Unmarshal([]byte(schemaStr), schema)
	if err != nil {
		t.Fatal(err)
	}

    // Marshal from Schema struct to JSON
	schemaBytes, err := json.Marshal(schema)
	if err != nil {
		t.Fatal(err)
	}
}

Contributions

Contributions are very welcome! This project is young and could use more eyes and brains to make everything better.
So please fork, code and make pull requests.
At least the existing tests should pass, but you're welcome to change those too, as long as the JSON Schema test suite is run and passes.

Currently most test for Draft 2019-09 and Draft 2020-12 passes, but there is more code to be done, before those 2 will be fully functional.

The JSON Schema parser is fairly slow and could probably be made faster, relatively easy.

Motivation for creating yet another JSON Schema parser / validator

The very nice gojsonschema was missing some features and we needed some internal functionality, that was hard to build on top of gojsonschema.

Furthermore gojsonschema uses Go's JSON parser, which makes it relatively slow, when parsing JSON documents for validation.
This module uses the excellent jsonparser, which is waaaay faster than Go's builtin parser.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewStringPtr

func NewStringPtr(b []byte) *string

func Validate

func Validate(jsonDoc []byte) (bool, error)

Validate will get $schema if it exists or fall back to latest supported Draft

Types

type Dependencies

type Dependencies map[string]*Dependency

func NewDependencies

func NewDependencies(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Dependencies, error)

func (Dependencies) MarshalJSON

func (d Dependencies) MarshalJSON() ([]byte, error)

type Dependency

type Dependency struct {
	Schema  *Schema
	Strings *Strings
}

func NewDependency

func NewDependency(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Dependency, error)

func (Dependency) MarshalJSON

func (i Dependency) MarshalJSON() ([]byte, error)

type Enum

type Enum []*Value

func NewEnum

func NewEnum(jsonVal []byte, vt jsonparser.ValueType) (*Enum, error)

func (Enum) MarshalJSON

func (e Enum) MarshalJSON() ([]byte, error)

type Items

type Items struct {
	Schema  *Schema
	Schemas *Schemas
	Boolean *bool
}

func NewItems

func NewItems(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Items, error)

func (Items) MarshalJSON

func (i Items) MarshalJSON() ([]byte, error)

type NamedProperty

type NamedProperty struct {
	Name     string
	Property *Schema
}

Properties are build like this, instead of map[string]*Schema, to make it possible to Marshal with original sort order of fields

type NamedValue added in v0.1.2

type NamedValue struct {
	Name string
	*Value
}

type Properties

type Properties []*NamedProperty

func NewProperties

func NewProperties(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Properties, error)

func (Properties) GetProperty

func (p Properties) GetProperty(name string) (*NamedProperty, bool)

func (Properties) MarshalJSON

func (p Properties) MarshalJSON() ([]byte, error)

type Ref

type Ref struct {
	String *string
	Schema *Schema `json:"-"`
	// contains filtered or unexported fields
}

func NewRef

func NewRef(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Ref, error)

func (Ref) MarshalJSON

func (r Ref) MarshalJSON() ([]byte, error)

type Schema

type Schema struct {
	Schema    *string `json:"$schema,omitempty"`
	ID        *string `json:"$id,omitempty"` // NOTE: draft-04 has id instead if $id
	IDDraft04 *string `json:"id,omitempty"`  // NOTE: draft-04 has id instead if $id
	Ref       *Ref    `json:"$ref,omitempty"`
	Comment   *string `json:"$comment,omitempty"`

	Title       *string `json:"title,omitempty"`
	Description *string `json:"description,omitempty"`

	Type *Type `json:"type,omitempty"`

	// Must have at least 1 value
	Enum     *Enum   `json:"enum,omitempty"`
	Default  *Value  `json:"default,omitempty"`
	Examples *Values `json:"examples,omitempty"`
	// Draft 6
	// Only allow 1 value
	Const *Value `json:"const,omitempty"`
	// Draft 7
	ReadOnly    *bool       `json:"readOnly,omitempty"`
	WriteOnly   *bool       `json:"writeOnly,omitempty"`
	Definitions *Properties `json:"definitions,omitempty"`
	// If schemas should look something like (const being the important part):
	//  { "if": { "properties": { "propertyX": { "const": "ValueX" } }, "required": ["propertyX"] } }
	If *Schema `json:"if,omitempty"`
	// One (or both?) of these can be omitted.
	// Both then and else will be ignore, if If is not defined.
	// If any of them are omitted, the value true is used in their place.
	// NOTE: It's not entirely obvious in the documentation, if both can be omitted:
	// https://json-schema.org/understanding-json-schema/reference/conditionals.html#if-then-else
	Then *Schema `json:"then,omitempty"`
	Else *Schema `json:"else,omitempty"`

	AllOf *Schemas `json:"allOf,omitempty"`
	AnyOf *Schemas `json:"anyOf,omitempty"`
	OneOf *Schemas `json:"oneOf,omitempty"`
	Not   *Schema  `json:"not,omitempty"`

	ContentEncoding  *string `json:"contentEncoding,omitempty"`  // e.g. base64
	ContentMediaType *string `json:"contentMediaType,omitempty"` // e.g. image/png

	Properties *Properties `json:"properties,omitempty"`
	// Draft 4 requires at least 1 string
	Required      *Strings `json:"required,omitempty"`
	MaxProperties *int64   `json:"maxProperties,omitempty"`
	MinProperties *int64   `json:"minProperties,omitempty"`
	// Dependencies is either:
	//  - if propertyX is set, then propertyY and propertyZ is required
	//     e.g.: { "propertyX": ["propertyY", "propertyZ"] }
	//  - if propertyX is set, then schemaX is also required to match
	//     e.g.: { "propertyX": { "properties": { "propertyY": { "type": "string" } }, "required": ["propertyY"] } }
	Dependencies *Dependencies `json:"dependencies,omitempty"`
	// patternProperties is used to match property names against a regex and for each a schema.
	// It's basically a map of schemas, but with regex instead of property names.
	PatternProperties *Properties `json:"patternProperties,omitempty"`

	// additionalProperties is a schema that will be used to validate any properties
	//  in the instance that are not matched by properties or patternProperties.
	// Setting it to false means no additional properties will be allowed.
	AdditionalProperties *Schema `json:"additionalProperties,omitempty"`
	//
	// Draft 6
	// Useful for enforcing a certain property name format
	// Property names implies { "type": "string" }
	// "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"}
	PropertyNames *Schema `json:"propertyNames,omitempty"`

	// When items is an array of multiples Schemas, each refers to their own index.
	Items       *Items `json:"items,omitempty"` // TODO: Can actually also be boolean
	MaxItems    *int64 `json:"maxItems,omitempty"`
	MinItems    *int64 `json:"minItems,omitempty"`
	UniqueItems *bool  `json:"uniqueItems,omitempty"`
	// Should only be evaluated when items is multiple schemas.
	// Any values that does not have an explicit schmea (multi schema),
	//  will validate according to this schema.
	// Setting it to false, means that no other values are allowed.
	AdditionalItems *Schema `json:"additionalItems,omitempty"`
	// contains only need to match 1 item in the documents array
	Contains *Schema `json:"contains,omitempty"`

	MaxLength *int64  `json:"maxLength,omitempty"`
	MinLength *int64  `json:"minLength,omitempty"`
	Format    *string `json:"format,omitempty"`
	Pattern   *string `json:"pattern,omitempty"`

	// The type (int/float) should of course match the type of the property
	MultipleOf *json.Number `json:"multipleOf,omitempty"`
	// Draft 4: x ≥ minimum unless exclusiveMinimum == true, x ≤ maximum unless exclusiveMaximum == true
	// Draft 6: x ≥ minimum, x > exclusiveMinimum, x ≤ maximum, x < exclusiveMaximum
	Maximum          *Value `json:"maximum,omitempty"`
	ExclusiveMaximum *Value `json:"exclusiveMaximum,omitempty"` // bool in draft 4
	Minimum          *Value `json:"minimum,omitempty"`
	ExclusiveMinimum *Value `json:"exclusiveMinimum,omitempty"` // bool in draft 4
	// contains filtered or unexported fields
}
var (
	Draft04Schema *Schema
	Draft06Schema *Schema
	Draft07Schema *Schema
)

func New

func New(schema []byte) (*Schema, error)

func NewFromString

func NewFromString(schema string) (*Schema, error)

func (*Schema) AddSchema

func (s *Schema) AddSchema(schema *Schema) error

func (*Schema) AddSchemaString

func (s *Schema) AddSchemaString(schemaString string) error

func (*Schema) DeRef

func (s *Schema) DeRef() error

func (*Schema) ExpandURI

func (s *Schema) ExpandURI(uri string) (*url.URL, error)

ExpandURI attempts to resolve a uri against the current Base URI

func (Schema) GetID

func (s Schema) GetID() string

func (*Schema) GetUnknown added in v0.1.1

func (s *Schema) GetUnknown(name string) (*Value, error)

func (Schema) IsDraft4

func (s Schema) IsDraft4() bool

func (Schema) IsDraft6

func (s Schema) IsDraft6() bool

func (Schema) IsDraft7

func (s Schema) IsDraft7() bool

func (Schema) IsEmpty

func (s Schema) IsEmpty() bool

Checks if everything is nil and thereby an empty schema, similar to a "true" schema TODO: Update with 20xx-xx props

func (Schema) MarshalJSON

func (s Schema) MarshalJSON() ([]byte, error)

func (*Schema) Parse

func (s *Schema) Parse(jsonSchema []byte) (*Schema, error)

func (Schema) Pretty

func (s Schema) Pretty() string

func (*Schema) ResolveRef

func (s *Schema) ResolveRef(ref *Ref) (*Schema, error)

func (*Schema) SetCircularRefThresHold

func (s *Schema) SetCircularRefThresHold(threshold int)

func (*Schema) SetID

func (s *Schema) SetID(id string)

func (*Schema) SetUnknown added in v0.1.1

func (s *Schema) SetUnknown(name string, val *Value) error

func (Schema) String

func (s Schema) String() string

func (*Schema) UnmarshalJSON

func (s *Schema) UnmarshalJSON(schema []byte) error

func (*Schema) Validate

func (s *Schema) Validate(jsonDoc []byte) (bool, error)

Validate will return on the first encounter of something invalid

type SchemaProp

type SchemaProp uint8
const (
	PropSchema SchemaProp = iota
	PropID
	PropIDDraft04
	PropRef
	PropComment
	PropTitle
	PropDescription
	PropType
	PropEnum
	PropDefault
	PropConst
	PropExamples
	PropReadOnly
	PropWriteOnly
	PropDefinitions
	PropIf
	PropThen
	PropElse
	PropAllOf
	PropAnyOf
	PropOneOf
	PropNot
	PropContentEncoding
	PropContentMediaType
	PropProperties
	PropRequired
	PropMaxProperties
	PropMinProperties
	PropDependencies
	PropPatternProperties
	PropAdditionalProperties
	PropPropertyNames
	PropItems
	PropMaxItems
	PropMinItems
	PropUniqueItems
	PropAdditionalItems
	PropContains
	PropMaxLength
	PropMinLength
	PropFormat
	PropPattern
	PropMultipleOf
	PropMaximum
	PropExclusiveMaximum
	PropMinimum
	PropExclusiveMinimum
)

TODO: Update with 20xx-xx props

type Schemas

type Schemas []*Schema

func NewSubSchemas

func NewSubSchemas(jsonVal []byte, vt jsonparser.ValueType, parentSchema *Schema) (*Schemas, error)

func (Schemas) MarshalJSON

func (s Schemas) MarshalJSON() ([]byte, error)

type Strings

type Strings []*string

func NewStrings

func NewStrings(jsonVal []byte, vt jsonparser.ValueType) (*Strings, error)

func (Strings) MarshalJSON

func (p Strings) MarshalJSON() ([]byte, error)

type Type

type Type struct {
	String  *string
	Strings *[]*string
}

func NewType

func NewType(jsonVal []byte, vt jsonparser.ValueType) (*Type, error)

func (*Type) Has

func (t *Type) Has(vt ValueType) bool

func (Type) MarshalJSON

func (t Type) MarshalJSON() ([]byte, error)

type Value

type Value struct {
	String  *string
	Number  *big.Float
	Boolean *bool
	Null    *bool
	Object  *map[string]*Value
	Array   *[]*Value
	// contains filtered or unexported fields
}

func NewValue

func NewValue(jsonVal []byte, vt jsonparser.ValueType) (*Value, error)

func (*Value) Equal

func (v *Value) Equal(val *Value) bool

func (Value) MarshalJSON

func (v Value) MarshalJSON() ([]byte, error)

func (Value) Raw added in v0.1.1

func (v Value) Raw() []byte

type ValueType

type ValueType uint8
const (
	NotExist ValueType = iota
	String
	Number
	Object
	Array
	Boolean
	Null
	Unknown
	Integer
)

These are the same as jsonparser.ValueType - except Integer, which jsonparser does not have

func DetectJSONType

func DetectJSONType(data []byte) ValueType

This should more or less match what jsonparser detects. Unfortunately jsonparser doesn't expose it's detect type function.

func (ValueType) ParserValueType

func (v ValueType) ParserValueType() jsonparser.ValueType

func (ValueType) String

func (v ValueType) String() string

type Values

type Values []*Value

func NewValues

func NewValues(jsonVal []byte, vt jsonparser.ValueType) (*Values, error)

func (Values) MarshalJSON

func (v Values) MarshalJSON() ([]byte, error)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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