schema

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2023 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package schema provides a validation framework for the API resources.

This package is part of the rest-layer project. See http://rest-layer.io for full REST Layer documentation.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// NewID is a field hook handler that generates a new globally unique id if
	// none exist, to be used in schema with OnInit.
	//
	// The generated ID is a Mongo like base64 object id (mgo/bson code has been
	// embedded into this function to prevent dep).
	NewID = func(ctx context.Context, value interface{}) interface{} {
		if value == nil {
			value = newID()
		}
		return value
	}

	// IDField is a common schema field configuration that generate an globally
	// unique id for new item id.
	IDField = Field{
		Description: "The item's id",
		Required:    true,
		ReadOnly:    true,
		OnInit:      NewID,
		Filterable:  true,
		Sortable:    true,
		Validator: &String{

			Regexp: "^[0-9a-v]{20}$",
		},
	}

	// SerialID is a common schema field configuration that generated and
	// maintained by storage layer.
	SerialID = Field{
		Description: "The item's auto increase id",
		Required:    true,
		ReadOnly:    true,
		Filterable:  true,
		Sortable:    true,
		Default:     "0",
		Validator: &String{
			Regexp: "^[0-9]{1,20}$",
		},
	}
)
View Source 
var (
	// Now is a field hook handler that returns the current time, to be used in
	// schema with OnInit and OnUpdate.
	Now = func(ctx context.Context, value interface{}) interface{} {
		return time.Now()
	}
	// CreatedField is a common schema field configuration for "created" fields.
	// It stores the creation date of the item.
	CreatedField = Field{
		Description: "The time at which the item has been inserted",
		Required:    true,
		ReadOnly:    true,
		OnInit:      Now,
		Sortable:    true,
		Validator:   &Time{},
	}

	// UpdatedField is a common schema field configuration for "updated" fields.
	// It stores the current date each time the item is modified.
	UpdatedField = Field{
		Description: "The time at which the item has been last updated",
		Required:    true,
		ReadOnly:    true,
		OnInit:      Now,
		OnUpdate:    Now,
		Sortable:    true,
		Validator:   &Time{},
	}
)
View Source 
var (
	// PasswordField is a common schema field for passwords. It encrypt the
	// password using bcrypt before storage and hide the value so the hash can't
	// be read back.
	PasswordField = Field{
		Description: "Write-only field storing a secret password.",
		Required:    true,
		Hidden:      true,
		Validator:   &Password{},
	}
)
View Source 
var Tombstone = internal{}

Tombstone is used to mark a field for removal.

Functions

func VerifyPassword 

func VerifyPassword(hash interface{}, password []byte) bool

VerifyPassword compare a field of an item payload containing a hashed password with a clear text password and return true if they match.

Types

type AllOf 

type AllOf []FieldValidator

AllOf validates that all the sub field validators validates. Be aware that the order of the validators matter, as the result of one successful validation is passed as input to the next.

func (AllOf) Compile 

func (v AllOf) Compile(rc ReferenceChecker) (err error)

Compile implements the ReferenceCompiler interface.

func (AllOf) GetField 

func (v AllOf) GetField(name string) *Field

GetField implements the FieldGetter interface. Note that it will return the first matching field only.

func (AllOf) Validate 

func (v AllOf) Validate(value interface{}) (interface{}, error)

Validate ensures that all sub-validators validates. Note the result of one successful validation is passed as input to the next. The result of the first error or last successful validation is returned.

func (AllOf) ValidateQuery 

func (v AllOf) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface. Note the result of one successful validation is passed as input to the next. The result of the first error or last successful validation is returned.

type AnyOf 

type AnyOf []FieldValidator

AnyOf validates if any of the sub field validators validates. If any of the sub field validators implements the FieldSerializer interface, the *first* implementation which does not error will be used.

func (AnyOf) Compile 

func (v AnyOf) Compile(rc ReferenceChecker) error

Compile implements the Compiler interface.

func (AnyOf) GetField 

func (v AnyOf) GetField(name string) *Field

GetField implements the FieldGetter interface. Note that it will return the first matching field only.

func (AnyOf) LessFunc 

func (v AnyOf) LessFunc() LessFunc

LessFunc implements the FieldComparator interface, and returns the first non-nil LessFunc or nil.

func (AnyOf) Serialize 

func (v AnyOf) Serialize(value interface{}) (interface{}, error)

Serialize attempts to serialize the value using the first available FieldSerializer which does not return an error. If no appropriate serializer is found, the input value is returned.

func (AnyOf) Validate 

func (v AnyOf) Validate(value interface{}) (interface{}, error)

Validate ensures that at least one sub-validator validates.

func (AnyOf) ValidateQuery 

func (v AnyOf) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface.

type Array 

type Array struct {
	// Values describes the properties for each array item.
	Values Field
	// MinLen defines the minimum array length (default 0).
	MinLen int
	// MaxLen defines the maximum array length (default no limit).
	MaxLen int
}

Array validates array values.

func (*Array) Compile 

func (v *Array) Compile(rc ReferenceChecker) (err error)

Compile implements the ReferenceCompiler interface.

func (Array) GetField 

func (v Array) GetField(name string) *Field

GetField implements the FieldGetter interface. It will return a Field if name corespond to a legal array index according to parameters set on v.

func (Array) Validate 

func (v Array) Validate(value interface{}) (interface{}, error)

Validate implements FieldValidator.

func (Array) ValidateQuery 

func (v Array) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements FieldQueryValidator.

type Bool 

type Bool struct {
}

Bool validates Boolean based values.

func (Bool) Validate 

func (v Bool) Validate(value interface{}) (interface{}, error)

Validate validates and normalize Boolean based value.

type Boundaries 

type Boundaries struct {
	Min float64
	Max float64
}

Boundaries defines min/max for an integer.

type Compiler 

type Compiler interface {
	Compile(rc ReferenceChecker) error
}

Compiler is similar to the Compiler interface, but intended for types that implements, or may hold, a reference. All nested types must implement this interface.

type Connection 

type Connection struct {
	Path      string
	Field     string
	Validator Validator
}

Connection is a dummy validator to define a weak connection to another schema. The query.Projection will treat this validator as an external resource, and generate a sub-request to fetch the sub-payload.

func (*Connection) Validate 

func (v *Connection) Validate(value interface{}) (interface{}, error)

Validate implements the FieldValidator interface.

type Dict 

type Dict struct {
	// KeysValidator is the validator to apply on dict keys.
	KeysValidator FieldValidator

	// Values describes the properties for each dict value.
	Values Field
	// MinLen defines the minimum number of fields (default 0).
	MinLen int
	// MaxLen defines the maximum number of fields (default no limit).
	MaxLen int
}

Dict validates objects with variadic keys.

Example 
package main

import (
	"github.com/entropyinf/rest-layer/schema"
)

func main() {
	_ = schema.Schema{
		Fields: schema.Fields{
			"dict": schema.Field{
				Validator: &schema.Dict{
					// Limit dict keys to foo and bar keys only
					KeysValidator: &schema.String{
						Allowed: []string{"foo", "bar"},
					},
					// Allow either string or integer as dict value
					Values: schema.Field{
						Validator: &schema.AnyOf{
							0: &schema.String{},
							1: &schema.Integer{},
						},
					},
				},
			},
		},
	}
}

Output:

func (*Dict) Compile 

func (v *Dict) Compile(rc ReferenceChecker) (err error)

Compile implements the ReferenceCompiler interface.

func (Dict) GetField 

func (v Dict) GetField(name string) *Field

GetField implements the FieldGetter interface.

func (Dict) Validate 

func (v Dict) Validate(value interface{}) (interface{}, error)

Validate implements FieldValidator interface.

type ErrorMap 

type ErrorMap map[string][]interface{}

ErrorMap contains a map of errors by field name.

func (ErrorMap) Error 

func (err ErrorMap) Error() string

Error implements the built-in error interface.

func (ErrorMap) Merge 

func (err ErrorMap) Merge(other ErrorMap)

Merge copies all errors from other into err.

type ErrorSlice 

type ErrorSlice []error

ErrorSlice contains a concatenation of several errors.

func (ErrorSlice) Append 

func (err ErrorSlice) Append(other error) ErrorSlice

Append adds an error to err and returns a new slice if others is not nil. If other is another ErrorSlice it is extended so that all elements are appended.

func (ErrorSlice) Error 

func (err ErrorSlice) Error() string

type Field 

type Field struct {
	// Description stores a short description of the field useful for automatic
	// documentation generation.
	Description string
	// Required throws an error when the field is not provided at creation.
	Required bool
	// ReadOnly throws an error when a field is changed by the client.
	// Default and OnInit/OnUpdate hooks can be used to set/change read-only
	// fields.
	ReadOnly bool
	// Hidden allows writes but hides the field's content from the client. When
	// this field is enabled, PUTing the document without the field would not
	// remove the field but use the previous document's value if any.
	Hidden bool
	// Default defines the value be stored on the field when when item is
	// created and this field is not provided by the client.
	Default interface{}
	// OnInit can be set to a function to generate the value of this field
	// when item is created. The function takes the current value if any
	// and returns the value to be stored.
	OnInit func(ctx context.Context, value interface{}) interface{}
	// OnUpdate can be set to a function to generate the value of this field
	// when item is updated. The function takes the current value if any
	// and returns the value to be stored.
	OnUpdate func(ctx context.Context, value interface{}) interface{}
	// Params defines a param handler for the field. The handler may change the field's
	// value depending on the passed parameters.
	Params Params
	// Handler is the piece of logic modifying the field value based on passed parameters.
	// This handler is only called if at least on parameter is provided.
	Handler FieldHandler
	// Validator is used to validate the field's format. Please note you *must* pass in pointers to
	// FieldValidator instances otherwise `schema` will not be able to discover other interfaces,
	// such as `Compiler`, and *will* prevent schema from initializing specific FieldValidators
	// correctly causing unexpected runtime errors.
	// @see http://research.swtch.com/interfaces for more details.
	Validator FieldValidator
	// Dependency rejects the field if the schema predicate doesn't match the document.
	// Use query.MustParsePredicate(`{field: "value"}`) to populate this field.
	Dependency Predicate
	// Filterable defines that the field can be used with the `filter` parameter.
	// When this property is set to `true`, you may want to ensure the backend
	// database has this field indexed.
	Filterable bool
	// Sortable defines that the field can be used with the `sort` parameter.
	// When this property is set to `true`, you may want to ensure the backend
	// database has this field indexed.
	Sortable bool
	// Schema can be set to a sub-schema to allow multi-level schema.
	Schema *Schema
}

Field specifies the info for a single field of a spec

func (Field) Compile 

func (f Field) Compile(rc ReferenceChecker) error

Compile implements the ReferenceCompiler interface and recursively compile sub schemas and validators when they implement Compiler interface.

type FieldComparator 

type FieldComparator interface {
	// LessFunc returns a valid LessFunc or nil. nil is returned when comparison
	// is not allowed.
	LessFunc() LessFunc
}

FieldComparator must be implemented by a FieldValidator that is to allow comparison queries ($gt, $gte, $lt and $lte). The returned LessFunc will be used by the query package's Predicate.Match functions, which is used e.g. by the internal mem storage backend.

type FieldGetter 

type FieldGetter interface {
	// GetField returns a Field for the given name if the name is allowed by
	// the schema. The field is expected to validate query values.
	//
	// You may reference a sub-field using dotted notation, e.g. field.subfield.
	GetField(name string) *Field
}

FieldGetter defines an interface for fetching sub-fields from a Schema or FieldValidator implementation that allows (JSON) object values.

type FieldHandler 

type FieldHandler func(ctx context.Context, value interface{}, params map[string]interface{}) (interface{}, error)

FieldHandler is the piece of logic modifying the field value based on passed parameters

type FieldQueryValidator 

type FieldQueryValidator interface {
	ValidateQuery(value interface{}) (interface{}, error)
}

FieldQueryValidator defines an interface for lightweight validation on field types, without applying constrains on the actual values.

type FieldSerializer 

type FieldSerializer interface {
	// Serialize is called when the data is coming from it internal storable
	// form and needs to be prepared for representation (i.e.: just before JSON
	// marshaling).
	Serialize(value interface{}) (interface{}, error)
}

FieldSerializer is used to convert the value between it's representation form and it internal storable form. A FieldValidator which implement this interface will have its Serialize method called before marshaling.

type FieldValidator 

type FieldValidator interface {
	Validate(value interface{}) (interface{}, error)
}

FieldValidator is an interface for all individual validators. It takes a value to validate as argument and returned the normalized value or an error if validation failed.

type FieldValidatorFunc 

type FieldValidatorFunc func(value interface{}) (interface{}, error)

FieldValidatorFunc is an adapter to allow the use of ordinary functions as field validators. If f is a function with the appropriate signature, FieldValidatorFunc(f) is a FieldValidator that calls f.

func (FieldValidatorFunc) Validate 

func (f FieldValidatorFunc) Validate(value interface{}) (interface{}, error)

Validate calls f(value).

type Fields 

type Fields map[string]Field

Fields defines a map of name -> field pairs

type Float 

type Float struct {
	Allowed    []float64
	Boundaries *Boundaries
}

Float validates float based values.

func (Float) LessFunc 

func (v Float) LessFunc() LessFunc

LessFunc implements the FieldComparator interface.

func (Float) Validate 

func (v Float) Validate(value interface{}) (interface{}, error)

Validate validates and normalize float based value.

func (Float) ValidateQuery 

func (v Float) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface

type IP 

type IP struct {
	// StoreBinary activates storage of the IP as binary to save space.
	// The storage requirement is 4 bytes for IPv4 and 16 bytes for IPv6.
	StoreBinary bool
}

IP validates IP values

func (IP) Serialize 

func (v IP) Serialize(value interface{}) (interface{}, error)

Serialize implements FieldSerializer.

func (IP) Validate 

func (v IP) Validate(value interface{}) (interface{}, error)

Validate implements FieldValidator

type Integer 

type Integer struct {
	Allowed    []int
	Boundaries *Boundaries
}

Integer validates integer based values.

func (Integer) LessFunc 

func (v Integer) LessFunc() LessFunc

LessFunc implements the FieldComparator interface.

func (Integer) Validate 

func (v Integer) Validate(value interface{}) (interface{}, error)

Validate validates and normalize integer based value.

func (Integer) ValidateQuery 

func (v Integer) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface

type LessFunc 

type LessFunc func(value, other interface{}) bool

LessFunc is a function that returns true only when value is less than other, and false in all other circumstances, including error conditions.

type Null 

type Null []FieldValidator

Null validates that the value is null.

func (Null) Validate 

func (v Null) Validate(value interface{}) (interface{}, error)

Validate ensures that value is null.

type Object 

type Object struct {
	Schema *Schema
}

Object validates objects which are defined by Schemas.

func (*Object) Compile 

func (v *Object) Compile(rc ReferenceChecker) error

Compile implements the ReferenceCompiler interface.

func (Object) GetField 

func (v Object) GetField(name string) *Field

GetField implements the FieldGetter interface.

func (Object) Validate 

func (v Object) Validate(value interface{}) (interface{}, error)

Validate implements FieldValidator interface.

type Param 

type Param struct {
	// Description of the parameter
	Description string
	// Validator to use for this parameter
	Validator FieldValidator
}

Param define an individual field parameter with its validator

type Params 

type Params map[string]Param

Params defines param name => definition pairs allowed for a field

type Password 

type Password struct {
	// MinLen defines the minimum password length (default 0).
	MinLen int
	// MaxLen defines the maximum password length (default no limit).
	MaxLen int
	// Cost sets a custom bcrypt hashing cost.
	Cost int
}

Password crypts a field password using bcrypt algorithm.

func (Password) Validate 

func (v Password) Validate(value interface{}) (interface{}, error)

Validate implements FieldValidator interface.

type Predicate 

type Predicate interface {
	Match(payload map[string]interface{}) bool
	Prepare(v Validator) error
}

Predicate is an interface matching the query.Predicate type.

func Q 

func Q() Predicate

Q is deprecated, use query.MustParsePredicate instead.

type Reference 

type Reference struct {
	Path string

	SchemaValidator Validator
	// contains filtered or unexported fields
}

Reference validates the ID of a linked resource.

func (*Reference) Compile 

func (r *Reference) Compile(rc ReferenceChecker) error

Compile validates v.Path against rc and stores the a FieldValidator for later use by v.Validate.

func (Reference) GetField 

func (r Reference) GetField(name string) *Field

GetField implements the FieldGetter interface.

func (Reference) Validate 

func (r Reference) Validate(value interface{}) (interface{}, error)

Validate validates and sanitizes IDs against the reference path.

type ReferenceChecker 

type ReferenceChecker interface {
	// ReferenceChecker should return a FieldValidator that can be used for validate that a referenced ID exists and
	// is of the right format. If there is no resource matching path, nil should e returned.
	ReferenceChecker(path string) (FieldValidator, Validator)
}

ReferenceChecker is used to retrieve a FieldValidator that can be used for validating referenced IDs.

type ReferenceCheckerFunc 

type ReferenceCheckerFunc func(path string) FieldValidator

ReferenceCheckerFunc is an adapter that allows ordinary functions to be used as reference checkers.

func (ReferenceCheckerFunc) ReferenceChecker 

func (f ReferenceCheckerFunc) ReferenceChecker(path string) FieldValidator

ReferenceChecker calls f(path).

type Schema 

type Schema struct {
	// Description of the object described by this schema.
	Description string
	// Fields defines the schema's allowed fields.
	Fields Fields
	// MinLen defines the minimum number of fields (default 0).
	MinLen int
	// MaxLen defines the maximum number of fields (default no limit).
	MaxLen int
}

Schema defines fields for a document.

func (Schema) Compile 

func (s Schema) Compile(rc ReferenceChecker) error

Compile implements the ReferenceCompiler interface and call the same function on each field. Note: if you use schema as a standalone library, it is the *caller's* responsibility to invoke the Compile method before using Prepare or Validate on a Schema instance, otherwise FieldValidator instances may not be initialized correctly.

func (Schema) GetField 

func (s Schema) GetField(name string) *Field

GetField implements the FieldGetter interface.

func (Schema) Prepare 

func (s Schema) Prepare(ctx context.Context, payload map[string]interface{}, original *map[string]interface{}, replace bool) (changes map[string]interface{}, base map[string]interface{})

Prepare takes a payload with an optional original payout when updating an existing item and return two maps, one containing changes operated by the user and another defining either existing data (from the current item) or data generated by the system thru "default" value or hooks.

If the original map is nil, prepare will act as if the payload is a new document. The OnInit hook is executed for each field if any, and default values are assigned to missing fields.

When the original map is defined, the payload is considered as an update on the original document, default values are not assigned, and only fields which are different than in the original are left in the change map. The OnUpdate hook is executed on each field.

If the replace argument is set to true with the original document set, the behavior is slightly different as any field not present in the payload but present in the original are set to nil in the change map (instead of just being absent). This instruct the validator that the field has been edited, so ReadOnly flag can throw an error and the field will be removed from the output document. The OnInit is also called instead of the OnUpdate.

func (Schema) Validate 

func (s Schema) Validate(changes map[string]interface{}, base map[string]interface{}) (doc map[string]interface{}, errs map[string][]interface{})

Validate validates changes applied on a base document in regard to the schema and generate an result document with the changes applied to the base document. All errors in the process are reported in the returned errs value.

type String 

type String struct {
	Regexp  string
	Allowed []string
	MaxLen  int
	MinLen  int
	// contains filtered or unexported fields
}

String validates string based values

func (*String) Compile 

func (v *String) Compile(rc ReferenceChecker) (err error)

Compile compiles and validate regexp if any.

func (String) Validate 

func (v String) Validate(value interface{}) (interface{}, error)

Validate validates and normalize string based value.

func (String) ValidateQuery 

func (v String) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface

type Time 

type Time struct {
	TimeLayouts []string // TimeLayouts is set of time layouts we want to validate.
	// contains filtered or unexported fields
}

Time validates time based values

func (*Time) Compile 

func (v *Time) Compile(rc ReferenceChecker) error

Compile the time formats.

func (Time) LessFunc 

func (v Time) LessFunc() LessFunc

LessFunc implements the FieldComparator interface.

func (Time) Validate 

func (v Time) Validate(value interface{}) (interface{}, error)

Validate validates and normalize time based value.

func (Time) ValidateQuery 

func (v Time) ValidateQuery(value interface{}) (interface{}, error)

ValidateQuery implements schema.FieldQueryValidator interface

type URL 

type URL struct {
	AllowRelative  bool
	AllowLocale    bool
	AllowNonHTTP   bool
	AllowedSchemes []string
}

URL validates URLs values.

func (URL) Validate 

func (v URL) Validate(value interface{}) (interface{}, error)

Validate validates URL values.

type Validator 

type Validator interface {
	GetField(name string) *Field
	Prepare(ctx context.Context, payload map[string]interface{}, original *map[string]interface{}, replace bool) (changes map[string]interface{}, base map[string]interface{})
	Validate(changes map[string]interface{}, base map[string]interface{}) (doc map[string]interface{}, errs map[string][]interface{})
}

Validator is an interface used to validate schema against actual data.

Source Files

View all Source files

Directories

Path Synopsis
Package encoding is the intended hierarchy location for encoding Schema to other formats.
 Package encoding is the intended hierarchy location for encoding Schema to other formats.
jsonschema
Package jsonschema provides JSON Schema Draft 4 encoding support for schema.Schema.
 Package jsonschema provides JSON Schema Draft 4 encoding support for schema.Schema.
Package query provides tools to query a schema defined by github.com/rs/schema.
 Package query provides tools to query a schema defined by github.com/rs/schema.

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.