schema

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2022 License: Apache-2.0 Imports: 12 Imported by: 13

README

schema 👍

GoDoc Build Status Codecov Go Report Card Version

Simplified JSON-Schema

This is a simplified, minimal implementation of JSON-Schema that is fast and has an easy API. If you're looking for a complete, rigorous implementation of JSON-Schema, you should try another tool.

What it Does

This library implements a sub-set of the JSON-Schema specification

What's Included
  • Unmarshal schema from JSON
  • Array, Boolean, Integer, Number, Object, and String type validators.
  • Custom Format rules
  • Happy API for accessing schema information, and walking a schema tree with a JSON-Pointer
What's Left Out
  • References
  • Loading remote Schemas by URI.

Pull Requests Welcome

This library is a work in progress, and will benefit from your experience reports, use cases, and contributions. If you have an idea for making Rosetta better, send in a pull request. We're all in this together! 👍

Documentation

Index

Examples

Constants

View Source 
const TypeAny = Type("any")

TypeAny is the token used by JSON-Schema to designate that any kind of data

View Source 
const TypeArray = Type("array")

TypeArray is the token used by JSON-Schema to designate that a schema describes an array.

View Source 
const TypeBoolean = Type("boolean")

TypeBoolean is the token used by JSON-Schema to designate that a schema describes an boolean.

View Source 
const TypeInteger = Type("integer")

TypeInteger is the token used by JSON-Schema to designate that a schema describes an integer.

View Source 
const TypeNumber = Type("number")

TypeNumber is the token used by JSON-Schema to designate that a schema describes an number.

View Source 
const TypeObject = Type("object")

TypeObject is the token used by JSON-Schema to designate that a schema describes an object.

View Source 
const TypeString = Type("string")

TypeString is the token used by JSON-Schema to designate that a schema describes an string.

View Source 
const ValidationErrorCode = 422

ValidationErrorCode represents HTTP Status Code: 422 "Unproccessable Entity"

Variables

This section is empty.

Functions

func UseFormat 

func UseFormat(name string, fn format.Function)

UseFormat adds a custom FormatFunc function to this library. Used to register custom validators

Types

type Array 

type Array struct {
	Items     Element
	MinLength int
	MaxLength int
	Required  bool
	Delimiter string // DEPRECATED
}

Array represents an array data type within a JSON-Schema.

func (Array) Clean added in v0.7.0 

func (element Array) Clean(value any) error

func (Array) DefaultValue added in v0.6.0 

func (element Array) DefaultValue() any

DefaultValue returns the default value for this element type

func (Array) Get 

func (element Array) Get(object reflect.Value, path list.List) (reflect.Value, error)

func (Array) GetElement added in v0.6.0 

func (element Array) GetElement(path list.List) (Element, error)

GetElement returns a sub-element of this schema

func (Array) IsRequired 

func (element Array) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (Array) MarshalMap 

func (element Array) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (Array) Remove added in v0.6.0 

func (element Array) Remove(object reflect.Value, path list.List) (reflect.Value, error)

func (Array) Set 

func (element Array) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set formats/validates a generic value using this schema

func (Array) Type 

func (element Array) Type() reflect.Type

Type returns the reflection type of this Element

func (*Array) UnmarshalMap 

func (element *Array) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (Array) Validate 

func (element Array) Validate(value any) error

Validate validates a value against this schema

type BoolGetter added in v0.7.0 

type BoolGetter interface {
	GetBool(string) (bool, error)
}

type BoolSetter added in v0.7.0 

type BoolSetter interface {
	SetBool(string, bool) error
}

type Boolean 

type Boolean struct {
	Default  null.Bool `json:"default"`
	Required bool
}

Boolean represents a boolean data type within a JSON-Schema.

func (Boolean) Clean added in v0.7.0 

func (element Boolean) Clean(value any) error

func (Boolean) DefaultValue added in v0.6.0 

func (element Boolean) DefaultValue() any

DefaultValue returns the default value for this element type

func (Boolean) Get 

func (element Boolean) Get(object reflect.Value, path list.List) (reflect.Value, error)

Find locates a child of this element

func (Boolean) GetElement added in v0.6.0 

func (element Boolean) GetElement(path list.List) (Element, error)

GetElement returns the element definition for a given path

func (Boolean) IsRequired 

func (element Boolean) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (Boolean) MarshalJSON 

func (element Boolean) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface

func (Boolean) MarshalMap 

func (element Boolean) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (Boolean) Remove added in v0.6.0 

func (element Boolean) Remove(_ reflect.Value, _ list.List) (reflect.Value, error)

Remove removes a value from the provided object/path. In the case of booleans, this is a no-op.

func (Boolean) Set 

func (element Boolean) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set formats a value and applies it to the provided object/path

func (Boolean) Type 

func (element Boolean) Type() reflect.Type

Type returns the data type of this Element

func (*Boolean) UnmarshalMap 

func (element *Boolean) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (Boolean) Validate 

func (element Boolean) Validate(object any) error

Validate validates a generic value using this schema

type Element 

type Element interface {

	// Type returns the Type of this particular schema element
	Type() reflect.Type

	// Default returns the default value for this element
	DefaultValue() any

	// IsRequired returns true if this a value is required for this element
	IsRequired() bool

	// Get uses the path to locate a value in an object.
	Get(object reflect.Value, path list.List) (reflect.Value, error)

	// GetElement finds the schema element that defines the property at the end of the path
	GetElement(path list.List) (Element, error)

	// Set formats a value and applies it to the provided object/path
	Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

	// Remove removes the value from the object at the designated path
	Remove(object reflect.Value, path list.List) (reflect.Value, error)

	// Validate validates the provided value
	Validate(value any) error

	// Clean updates a value to match the schema.  The value must be a pointer.
	Clean(value any) error

	// MarshalMap populates the object data into a map[string]any
	MarshalMap() map[string]any
}

Element interface wraps all of the methods required for schema elements.

func UnmarshalJSON 

func UnmarshalJSON(data []byte) (Element, error)

UnmarshalJSON tries to parse a []byte into a schema.Element

func UnmarshalMap 

func UnmarshalMap(data any) (Element, error)

UnmarshalMap tries to parse a map[string]any into a schema.Element

type ElementMap 

type ElementMap map[string]Element

type Enumerator 

type Enumerator interface {
	Enumerate() []string
}

type FloatGetter added in v0.7.0 

type FloatGetter interface {
	GetFloat(string) (float64, error)
}

type FloatSetter added in v0.7.0 

type FloatSetter interface {
	SetFloat(string, float64) error
}

type Getter added in v0.7.0 

type Getter interface {
	Get(string) (any, error)
}

type Int64Getter added in v0.7.0 

type Int64Getter interface {
	GetInt64(string) (int64, error)
}

type Int64Setter added in v0.7.0 

type Int64Setter interface {
	SetInt64(string, int64) error
}

type IntGetter added in v0.7.0 

type IntGetter interface {
	GetInt(string) (int, error)
}

type IntSetter added in v0.7.0 

type IntSetter interface {
	SetInt(string, int) error
}

type Integer 

type Integer struct {
	Default    null.Int64 `json:"default"`
	Minimum    null.Int64 `json:"minimum"`
	Maximum    null.Int64 `json:"maximum"`
	MultipleOf null.Int64 `json:"multipleOf"`
	BitSize    int        `json:"bitSize"`
	Enum       []int      `json:"emum"`
	Required   bool
}

Integer represents an integer data type within a JSON-Schema.

func (Integer) Clean added in v0.7.0 

func (element Integer) Clean(value any) error

func (Integer) DefaultValue added in v0.6.0 

func (element Integer) DefaultValue() any

DefaultValue returns the default value for this element type

func (Integer) Enumerate 

func (element Integer) Enumerate() []string

Enumerate implements the "Enumerator" interface

func (Integer) Get 

func (element Integer) Get(object reflect.Value, path list.List) (reflect.Value, error)

func (Integer) GetElement added in v0.6.0 

func (element Integer) GetElement(path list.List) (Element, error)

GetElement returns a sub-element of this schema

func (Integer) IsRequired 

func (element Integer) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (Integer) MarshalMap 

func (element Integer) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (Integer) Remove added in v0.6.0 

func (element Integer) Remove(_ reflect.Value, _ list.List) (reflect.Value, error)

Remove removes a value from the provided object/path. In the case of integers, this is a no-op.

func (Integer) Set 

func (element Integer) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set formats a value and applies it to the provided object/path

func (Integer) Type 

func (element Integer) Type() reflect.Type

Type returns the data type of this Schema

func (*Integer) UnmarshalMap 

func (element *Integer) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (Integer) Validate 

func (element Integer) Validate(value any) error

Validate validates a value using this schema

type Nullable 

type Nullable interface {
	IsNull() bool
}

Nullable interface wraps the IsNull method, that helps an object to identify if it contains a null value or not. This mirrors the null.Nullable interface here, for convenience.

type Number 

type Number struct {
	Default    null.Float `json:"default"`
	Minimum    null.Float `json:"minimum"`
	Maximum    null.Float `json:"maximum"`
	MultipleOf null.Float `json:"multipleOf"`
	BitSize    int        `json:"bitSize"`
	Enum       []float64  `json:"enum"`
	Required   bool
}

Number represents a number data type within a JSON-Schema.

func (Number) Clean added in v0.7.0 

func (element Number) Clean(value any) error

func (Number) DefaultValue added in v0.6.0 

func (element Number) DefaultValue() any

DefaultValue returns the default value for this element type

func (Number) Enumerate 

func (element Number) Enumerate() []string

Enumerate implements the "Enumerator" interface

func (Number) Get 

func (element Number) Get(object reflect.Value, path list.List) (reflect.Value, error)

func (Number) GetElement added in v0.6.0 

func (element Number) GetElement(path list.List) (Element, error)

GetElement returns a sub-element of this schema

func (Number) IsRequired 

func (element Number) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (Number) MarshalMap 

func (element Number) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (Number) Remove added in v0.6.0 

func (element Number) Remove(_ reflect.Value, _ list.List) (reflect.Value, error)

Remove removes a value from the provided object/path. In the case of numbers, this is a no-op.

func (Number) Set 

func (element Number) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set formats a value and applies it to the provided object/path

func (Number) Type 

func (element Number) Type() reflect.Type

Type returns the data type of this Element

func (*Number) UnmarshalMap 

func (element *Number) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (Number) Validate 

func (element Number) Validate(value any) error

Validate validates a value against this schema

type Object 

type Object struct {
	Properties    ElementMap
	Unlisted      Element
	RequiredProps []string
	Required      bool
}

Object represents an object data type within a JSON-Schema.

func (Object) Clean added in v0.7.0 

func (element Object) Clean(value any) error

func (Object) DefaultValue added in v0.6.0 

func (element Object) DefaultValue() any

DefaultValue returns the default value for this element type. In a special case for objects, which can be represented as both Go structs and maps, this returns a map[string]any that has been populated with any known default keys.

func (Object) Get 

func (element Object) Get(object reflect.Value, path list.List) (reflect.Value, error)

Find locates a child of this element

func (Object) GetElement added in v0.6.0 

func (element Object) GetElement(path list.List) (Element, error)

GetElement returns a sub-element of this schema

func (Object) IsRequired 

func (element Object) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (Object) MarshalMap 

func (element Object) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (Object) Remove added in v0.6.0 

func (element Object) Remove(object reflect.Value, path list.List) (reflect.Value, error)

Remove removes a child of the target object. In the case of Maps, the map key is removed. In the case of Structs, the field is set to its default value.

func (Object) Set 

func (element Object) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set validates/formats a value using this schema

func (Object) Type 

func (element Object) Type() reflect.Type

Type returns the data type of this Element

func (*Object) UnmarshalMap 

func (element *Object) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (Object) Validate 

func (element Object) Validate(value any) error

Validate validates a value against this schema

type Schema 

type Schema struct {
	ID      string
	Comment string
	Element Element
}

Schema defines a (simplified) JSON-Schema object, that can be Marshalled/Unmarshalled to JSON.

func New 

func New(element Element) Schema

New generates a fully initialized Schema object using the provided properties

func Unmarshal 

func Unmarshal(original string) Schema

Unmarshal converts a JSON string into a schema. If the string cannot be converted, then an empty schema is returned.

func (Schema) Clean added in v0.7.0 

func (schema Schema) Clean(value any) error

Clean tries to force a particular value to fit this schema by updating it (or all of its properties) to match. If values cannot be coerced to fit the schema, then an error is returned

func (Schema) DefaultValue added in v0.6.0 

func (schema Schema) DefaultValue() any

DefaultValue returns a value that matches the defaults for this schema.

func (*Schema) ElementType added in v0.6.0 

func (schema *Schema) ElementType() reflect.Type

ElementType returns the reflection type of this schema's top-level element

func (Schema) Get 

func (schema Schema) Get(object any, path string) (any, error)

Get retrieves a generic value from the object. If the object is nil, Get still tries to return a default value if provided by the schema

func (Schema) GetBool 

func (schema Schema) GetBool(object any, path string) bool

GetBool retrieves a bool value from this object. If the value is not defined in the object/schema, then the zero value (false) is returned

func (Schema) GetElement added in v0.6.0 

func (schema Schema) GetElement(path string) (Element, error)

func (Schema) GetFloat 

func (schema Schema) GetFloat(object any, path string) float64

GetFloat retrieves a float64 value from this object. If the value is not defined in the object/schema, then the zero value (0.0) is returned

func (Schema) GetInt 

func (schema Schema) GetInt(object any, path string) int

GetInt retrieves a int value from this object. If the value is not defined in the object/schema, then the zero value (0) is returned

func (Schema) GetInt64 

func (schema Schema) GetInt64(object any, path string) int64

GetInt64 retrieves an int64 value from this object. If the value is not defined in the object/schema, then the zero value (0) is returned

func (Schema) GetString 

func (schema Schema) GetString(object any, path string) string

GetString retrieves a string value from this object. If the value is not defined in the object/schema, then the zero value ("") is returned

func (Schema) MarshalJSON 

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

MarshalJSON converts a schema into JSON.

func (Schema) MarshalMap 

func (schema Schema) MarshalMap() map[string]any

MarshalMap converts a schema into a map[string]any

func (Schema) Remove added in v0.6.0 

func (schema Schema) Remove(object any, path string) error

func (Schema) Set 

func (schema Schema) Set(object any, path string, value any) error

Schema applies a value to the object at the given path. If the path is invalid then it returns an error

func (Schema) SetAll 

func (schema Schema) SetAll(object any, values map[string]any) error

SetAll iterates over Set to apply all of the values to the object one at a time, stopping at the first error it encounters. If all values are addedd successfully, then SetAll also uses Validate() to confirm that the object is still correct.

func (*Schema) UnmarshalJSON 

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

UnmarshalJSON creates a new Schema object using a JSON-serialized byte array.

func (*Schema) UnmarshalMap 

func (schema *Schema) UnmarshalMap(data map[string]any) error

UnmarshalMap updates a Schema using a map[string]any

func (Schema) Validate 

func (schema Schema) Validate(value any) error

Validate checks a particular value against this schema. If the provided value is not valid, then an error is returned.

type Setter added in v0.7.0 

type Setter interface {
	Set(string, any) error
}

type String 

type String struct {
	Default   string
	MinLength int
	MaxLength int
	Enum      []string
	Pattern   string
	Format    string
	Required  bool
}

String represents a string data type within a JSON-Schema.

func (String) Clean added in v0.7.0 

func (element String) Clean(value any) error

func (String) DefaultValue added in v0.6.0 

func (element String) DefaultValue() any

DefaultValue returns the default value for this element type

func (String) Enumerate 

func (element String) Enumerate() []string

Enumerate implements the "Enumerator" interface

func (String) Get 

func (element String) Get(object reflect.Value, path list.List) (reflect.Value, error)

func (String) GetElement added in v0.6.0 

func (element String) GetElement(path list.List) (Element, error)

GetElement returns a sub-element of this schema

func (String) IsRequired 

func (element String) IsRequired() bool

IsRequired returns TRUE if this element is a required field

func (String) MarshalMap 

func (element String) MarshalMap() map[string]any

MarshalMap populates object data into a map[string]any

func (String) Remove added in v0.6.0 

func (element String) Remove(_ reflect.Value, _ list.List) (reflect.Value, error)

Remove removes a value from the provided object/path. In the case of strings, this is a no-op.

func (String) Set 

func (element String) Set(object reflect.Value, path list.List, value any) (reflect.Value, error)

Set validates/formats a generic value using this schema

func (String) Type 

func (element String) Type() reflect.Type

Type returns the data type of this Element

func (*String) UnmarshalMap 

func (element *String) UnmarshalMap(data map[string]any) error

UnmarshalMap tries to populate this object using data from a map[string]any

func (String) Validate 

func (element String) Validate(value any) error

Validate compares a generic data value using this Schema

type StringGetter added in v0.7.0 

type StringGetter interface {
	GetString(string) (string, error)
}

type StringSetter added in v0.7.0 

type StringSetter interface {
	SetString(string, string) error
}

type Type 

type Type string

Type enumerates all of the data types that can make up a schema

func (Type) String 

func (schemaType Type) String() string

String implements the ubiquitous "Stringer" interface, so that these types can be represented as strings, if necessary

type ValidationError 

type ValidationError struct {
	Path    string `json:"path"`    // Identifies the PATH (or variable name) that has invalid input
	Message string `json:"message"` // Human-readable message that explains the problem with the input value.
}

ValidationError represents an input validation error, and includes fields necessary to report problems back to the end user.

Example 
// Derp includes a custom error type for data validation, that tracks
// the name (or path) of the invalid field and the reason that it is invalid

err := Invalid("Field is required, or is too short, or is something else we don't like.")

// ValidationErrors work anywhere that a standard error works
fmt.Println(err.Error())

// Derp can also calculates the HTTP error code for ValidationErrors, which is 422 "Unprocessable Entity".
fmt.Println(derp.ErrorCode(err))

Output:

Field is required, or is too short, or is something else we don't like.
422

func Invalid 

func Invalid(message string) ValidationError

Invalid returns a fully populated ValidationError to the caller

func (ValidationError) Error 

func (v ValidationError) Error() string

Error returns a string representation of this ValidationError, and implements the builtin errors.error interface.

func (ValidationError) ErrorCode 

func (v ValidationError) ErrorCode() int

ErrorCode returns CodeValidationError for this ValidationError It implements the ErrorCodeGetter interface.

type WritableElement 

type WritableElement interface {

	// UnmarshalMap tries to populate this object using data from a map[string]any
	UnmarshalMap(map[string]any) error

	Element
}

WritableElement represents an Element (usually a pointer to a concrete type) whose value can be changed.

Source Files

View all Source files

Directories

Path Synopsis

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.