Documentation
¶
Overview ¶
Package jsonschema provides helpers for validating JSON and YAML content against JSON Schema documents.
The package wraps github.com/santhosh-tekuri/jsonschema/v6 and standardises a few behaviours used across this repository:
- schema definitions can be described as files and loaded from either the normal filesystem or an embedded filesystem
- raw JSON values, raw YAML bytes, JSON files, and YAML files can all be validated through the same schema abstraction
- validation and loading failures are wrapped with the repository's common error types so callers can test and report them consistently
- when a schema is composed of multiple schema documents, callers may pass an optional schema ID to select the root schema to compile; otherwise it should be left as nil
In normal use, callers describe one or more schema files with Schema values, optionally pass a schema ID when the schema set is composed of multiple documents, and then validate either raw content or files through the helper functions in this package.
Index ¶
- func ValidateJSONFileAgainstSchema(ctx context.Context, filePath string, schemaID *string, schema ...Schema) error
- func ValidateJSONFileAgainstSchemaFS(ctx context.Context, fileSystem filesystem.FS, filePath string, ...) error
- func ValidateJSONFileAgainstSchemaFSWithOptions(ctx context.Context, fileSystem filesystem.FS, filePath string, ...) error
- func ValidateJSONFileAgainstSchemaOptions(ctx context.Context, filePath string, options ...SchemaOption) error
- func ValidateRawJSONAgainstSchema(ctx context.Context, content any, schemaID *string, schema ...Schema) error
- func ValidateRawJSONAgainstSchemaOptions(ctx context.Context, content any, options ...SchemaOption) error
- func ValidateRawYAMLAgainstSchema(ctx context.Context, content []byte, schemaID *string, schema ...Schema) error
- func ValidateRawYAMLAgainstSchemaOptions(ctx context.Context, content []byte, options ...SchemaOption) error
- func ValidateYAMLFileAgainstSchema(ctx context.Context, filePath string, schemaID *string, schema ...Schema) error
- func ValidateYAMLFileAgainstSchemaFS(ctx context.Context, fileSystem filesystem.FS, filePath string, ...) error
- func ValidateYAMLFileAgainstSchemaFSWithOptions(ctx context.Context, fileSystem filesystem.FS, filePath string, ...) error
- func ValidateYAMLFileAgainstSchemaOptions(ctx context.Context, filePath string, options ...SchemaOption) error
- type ISchemaValidator
- func NewJSONFileValidator(schemaID *string, schema ...Schema) (v ISchemaValidator, err error)
- func NewJSONFileValidatorWithOptions(options ...SchemaOption) (ISchemaValidator, error)
- func NewYAMLFileValidator(schemaID *string, schema ...Schema) (v ISchemaValidator, err error)
- func NewYAMLFileValidatorWithOptions(options ...SchemaOption) (ISchemaValidator, error)
- type Schema
- type SchemaOption
- type SchemaSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateJSONFileAgainstSchema ¶
func ValidateJSONFileAgainstSchema(ctx context.Context, filePath string, schemaID *string, schema ...Schema) error
ValidateJSONFileAgainstSchema validates a JSON file from the global filesystem against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
func ValidateJSONFileAgainstSchemaFS ¶
func ValidateJSONFileAgainstSchemaFS(ctx context.Context, fileSystem filesystem.FS, filePath string, schemaID *string, schema ...Schema) error
ValidateJSONFileAgainstSchemaFS validates a JSON file from the supplied filesystem against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
func ValidateJSONFileAgainstSchemaFSWithOptions ¶
func ValidateJSONFileAgainstSchemaFSWithOptions(ctx context.Context, fileSystem filesystem.FS, filePath string, options ...SchemaOption) error
ValidateJSONFileAgainstSchemaFSWithOptions validates a JSON file from the supplied filesystem against a Schema built from the supplied options.
func ValidateJSONFileAgainstSchemaOptions ¶
func ValidateJSONFileAgainstSchemaOptions(ctx context.Context, filePath string, options ...SchemaOption) error
ValidateJSONFileAgainstSchemaOptions validates a JSON file against a Schema built from the supplied options.
func ValidateRawJSONAgainstSchema ¶
func ValidateRawJSONAgainstSchema(ctx context.Context, content any, schemaID *string, schema ...Schema) error
ValidateRawJSONAgainstSchema validates JSON-compatible content against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
The content may already be decoded into Go values, or any other value that can be passed directly to the underlying JSON Schema validator.
func ValidateRawJSONAgainstSchemaOptions ¶
func ValidateRawJSONAgainstSchemaOptions(ctx context.Context, content any, options ...SchemaOption) error
ValidateRawJSONAgainstSchemaOptions validates JSON-compatible content against a Schema built from the supplied options.
func ValidateRawYAMLAgainstSchema ¶
func ValidateRawYAMLAgainstSchema(ctx context.Context, content []byte, schemaID *string, schema ...Schema) error
ValidateRawYAMLAgainstSchema validates raw YAML bytes against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
The YAML content is converted to JSON first and then validated against the compiled JSON Schema.
func ValidateRawYAMLAgainstSchemaOptions ¶
func ValidateRawYAMLAgainstSchemaOptions(ctx context.Context, content []byte, options ...SchemaOption) error
ValidateRawYAMLAgainstSchemaOptions validates raw YAML bytes against a Schema built from the supplied options.
func ValidateYAMLFileAgainstSchema ¶
func ValidateYAMLFileAgainstSchema(ctx context.Context, filePath string, schemaID *string, schema ...Schema) error
ValidateYAMLFileAgainstSchema validates a YAML file from the global filesystem against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
func ValidateYAMLFileAgainstSchemaFS ¶
func ValidateYAMLFileAgainstSchemaFS(ctx context.Context, fileSystem filesystem.FS, filePath string, schemaID *string, schema ...Schema) error
ValidateYAMLFileAgainstSchemaFS validates a YAML file from the supplied filesystem against the supplied schema definitions.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
func ValidateYAMLFileAgainstSchemaFSWithOptions ¶
func ValidateYAMLFileAgainstSchemaFSWithOptions(ctx context.Context, fileSystem filesystem.FS, filePath string, options ...SchemaOption) error
ValidateYAMLFileAgainstSchemaFSWithOptions validates a YAML file from the supplied filesystem against a Schema built from the supplied options.
func ValidateYAMLFileAgainstSchemaOptions ¶
func ValidateYAMLFileAgainstSchemaOptions(ctx context.Context, filePath string, options ...SchemaOption) error
ValidateYAMLFileAgainstSchemaOptions validates a YAML file against a Schema built from the supplied options.
Types ¶
type ISchemaValidator ¶
type ISchemaValidator interface {
// ValidateContent validates already-loaded content against the compiled
// schema definition.
ValidateContent(context.Context, any) error
// ValidateFile validates a file from the global filesystem against the
// compiled schema definition.
ValidateFile(ctx context.Context, filepath string) error
// ValidateFileWithLimits validates a file from the global filesystem against the
// compiled schema definition.
ValidateFileWithLimits(ctx context.Context, filepath string, fileLimits filesystem.ILimits) error
// ValidateFileInFS validates a file from the supplied filesystem against the
// compiled schema definition.
ValidateFileInFS(ctx context.Context, fs filesystem.FS, filepath string) error
// ValidateFileInFSWithLimits validates a file from the supplied filesystem against the
// compiled schema definition.
ValidateFileInFSWithLimits(ctx context.Context, fs filesystem.FS, filepath string, fileLimits filesystem.ILimits) error
}
ISchemaValidator validates content against a compiled JSON Schema definition.
Implementations may support different source formats such as JSON or YAML, but all expose the same three entry points: validating already-loaded content, validating a file from the global filesystem, and validating a file from a supplied filesystem.
func NewJSONFileValidator ¶
func NewJSONFileValidator(schemaID *string, schema ...Schema) (v ISchemaValidator, err error)
NewJSONFileValidator returns a validator for JSON content and `.json` files.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
The returned validator compiles its schema set lazily and caches the result for reuse across subsequent validations.
func NewJSONFileValidatorWithOptions ¶
func NewJSONFileValidatorWithOptions(options ...SchemaOption) (ISchemaValidator, error)
NewJSONFileValidatorWithOptions returns a JSON validator using a Schema built from the supplied options.
func NewYAMLFileValidator ¶
func NewYAMLFileValidator(schemaID *string, schema ...Schema) (v ISchemaValidator, err error)
NewYAMLFileValidator returns a validator for YAML content and `.yaml` or `.yml` files.
`schemaID` is the optional schema ID to compile when the schema is composed of multiple schema documents. Otherwise, leave it as nil.
The returned validator compiles its schema set lazily and caches the result for reuse across subsequent validations.
func NewYAMLFileValidatorWithOptions ¶
func NewYAMLFileValidatorWithOptions(options ...SchemaOption) (ISchemaValidator, error)
NewYAMLFileValidatorWithOptions returns a YAML validator using a Schema built from the supplied options.
type Schema ¶
type Schema struct {
// Title is a human-readable title of the schema.
Title string
// LocalPath is the path to the schema file. It should be available on the
// filesystem or an embedded filesystem.
LocalPath string
// ID should match the $id field within the schema.
ID string
// Filesystem is the filesystem to use to load the schema file.
Filesystem filesystem.FS
// Limits defines the filesystem read limits used when loading the schema
// file.
Limits filesystem.ILimits
}
Schema describes a schema file that can be loaded and registered for validation.
It is intended to be a lightweight wrapper around a schema file so callers can build validators from normal or embedded filesystems without passing raw schema bytes around manually.
func DefaultSchema ¶
func DefaultSchema() *Schema
DefaultSchema returns a Schema initialised with the package defaults.
The default filesystem is the global filesystem, and the schema ID is derived from the local path when it has not been set explicitly.
func NewJSONSchemaFile ¶
func NewJSONSchemaFile(options ...SchemaOption) *Schema
NewJSONSchemaFile constructs a Schema from the supplied options.
Options are applied in order, after which the package defaults are materialised.
func (*Schema) Apply ¶
func (s *Schema) Apply(option SchemaOption) *Schema
Apply applies a single option to a Schema and then reapplies defaults.
type SchemaOption ¶
SchemaOption configures a Schema during construction.
func WithFileLimits ¶
func WithFileLimits(limits filesystem.ILimits) SchemaOption
WithFileLimits sets the filesystem read limits used when loading the Schema file.
A nil limits value falls back to filesystem.NoLimits().
func WithFilesystem ¶
func WithFilesystem(fs filesystem.FS) SchemaOption
WithFilesystem sets the filesystem used to load the Schema file.
A nil filesystem falls back to the global filesystem, and the current local path is cleaned for that filesystem.
func WithID ¶
func WithID(id string) SchemaOption
WithID sets the schema ID of a Schema.
If the supplied ID is empty, schemaID falls back to the current local path.
func WithLocalPath ¶
func WithLocalPath(localPath string) SchemaOption
WithLocalPath sets the local path of a Schema file.
The path is trimmed, and the schema ID is recalculated with schemaID when no explicit ID has been provided.
func WithTitle ¶
func WithTitle(title string) SchemaOption
WithTitle sets the human-readable title of a Schema.
type SchemaSpec ¶
type SchemaSpec struct {
ID string
Specification []byte
// Title is a human-readable title of the schema.
Title string
}
SchemaSpec contains the raw JSON schema document and the identifier used to register it with the JSON Schema compiler.
func LoadSchemaSpec ¶
func LoadSchemaSpec(ctx context.Context, schema *Schema) (*SchemaSpec, error)
LoadSchemaSpec reads and returns the raw schema specification described by schema.
The schema file is read from the filesystem attached to the Schema, which may be a normal or embedded filesystem.
func (*SchemaSpec) Validate ¶
func (s *SchemaSpec) Validate() error
Validate checks that the schema specification contains the required fields needed to register and compile a schema.
Source Files