validation

Documentation

Overview

Package validation checks Lambda inputs and outputs against JSON Schema.

Compile prepares a reusable Schema; Schema.Validate checks a payload against it. Validate combines compilation and validation for one-off calls. Options configures extraction, compilation and error behavior. WrapHandler validates typed handler inputs and optional outputs.

Dialect and diagnostics

The default pure-Go backend implements the documented Draft 7 compatibility scope, with controlled keyword, format, reference and regular-expression rules. Structured issues retain schema and payload locations. It is not a claim of complete compatibility with every JSON Schema engine or extension. Draft202012Compiler and Draft201909Compiler select their native dialects with native diagnostics, leaving the default compiler's dialect/AJV contract unchanged.

Compile stable schemas during initialization and reuse them during invocations. Use the separate Parser module for composable typed Go schemas; Validation's engine dependencies do not become dependencies of Parser or core Commons.

For usage and compatibility details, see the user guide.

Index

• func Validate(ctx context.Context, payload, schema any, options Options) (any, error)
• func WrapHandler[I, T, R any](inbound, outbound *Schema, handler func(context.Context, T) (R, error)) func(context.Context, I) (R, error)
• type CompileOptions
• type Compiler
• type Draft201909Compiler
  • func (Draft201909Compiler) Compile(ctx context.Context, input any, options CompileOptions) (Validator, error)
• type Draft202012Compiler
  • func (Draft202012Compiler) Compile(ctx context.Context, input any, options CompileOptions) (Validator, error)
• type Issue
• type Options
• type RegexError
  • func (e *RegexError) Error() string
  • func (e *RegexError) Unwrap() error
• type RegexOptions
• type Schema
  • func Compile(ctx context.Context, schema any, options Options) (*Schema, error)
  • func (s *Schema) Validate(ctx context.Context, payload any) (any, error)
• type SchemaCompilationError
  • func (e *SchemaCompilationError) Error() string
  • func (e *SchemaCompilationError) Unwrap() error
• type SchemaValidationError
  • func (e *SchemaValidationError) Error() string
  • func (e *SchemaValidationError) Unwrap() error
• type Validator
• type ValidatorFunc
  • func (f ValidatorFunc) Validate(ctx context.Context, input any) ([]Issue, error)

Examples

• Compile
• Draft201909Compiler
• Draft202012Compiler

Functions

func Validate

func Validate(ctx context.Context, payload, schema any, options Options) (any, error)

Validate compiles for this call, then extracts and validates the payload. Use Compile once for warm-invocation reuse.

func WrapHandler

func WrapHandler[I, T, R any](inbound, outbound *Schema, handler func(context.Context, T) (R, error)) func(context.Context, I) (R, error)

WrapHandler validates a cloned inbound event and a successful outbound response. Only inbound validation applies an envelope; business errors and panics propagate.

Types

type CompileOptions

type CompileOptions struct {
	Regex   RegexOptions
	Formats map[string]func(any) error
	// NumberFormats applies callbacks to JSON numbers rather than strings.
	NumberFormats map[string]func(any) error
	// ExternalRefs registers URL-keyed documents in lexical URL order.
	ExternalRefs map[string]any
	// ExternalSchemas registers documents by $id in slice order, after ExternalRefs.
	// Use it when nested resource identities depend on registration order.
	ExternalSchemas []any
}

type Compiler

type Compiler interface {
	Compile(context.Context, any, CompileOptions) (Validator, error)
}

type Draft201909Compiler

type Draft201909Compiler struct{}

Draft201909Compiler selects JSON Schema Draft 2019-09 through Options.Compiler. Tuple items/additionalItems and recursive anchors follow this dialect's engine. Registration, snapshots, formats, cancellation and native diagnostics follow Draft202012Compiler; declarations and keywords are checked independently. This does not expand the default Draft 7 compiler or promise AJV error parity.

Example

package main

import (
	"context"
	"encoding/json/jsontext"
	"fmt"

	"github.com/rambow-cloud/powertools-lambda-go/validation"
)

func main() {
	schema, err := validation.Compile(context.Background(), jsontext.Value(`{
        "$schema":"https://json-schema.org/draft/2019-09/schema",
        "type":"array","items":[{"type":"integer"},{"type":"string"}],"additionalItems":false
    }`), validation.Options{Compiler: validation.Draft201909Compiler{}})
	if err != nil {
		panic(err)
	}
	_, valid := schema.Validate(context.Background(), []any{1, "ok"})
	_, extra := schema.Validate(context.Background(), []any{1, "ok", true})
	fmt.Println(valid == nil, extra != nil)
}

Output:
true true

func (Draft201909Compiler) Compile

func (Draft201909Compiler) Compile(ctx context.Context, input any, options CompileOptions) (Validator, error)

type Draft202012Compiler

type Draft202012Compiler struct{}

Draft202012Compiler selects JSON Schema Draft 2020-12 through Options.Compiler. It leaves the default Draft 7 compiler unchanged. Schemas and references are snapshotted; only registered references can load. Formats are asserted using the engine's built-ins and registered callbacks; content remains annotation. Diagnostics are native engine leaf errors, not AJV messages or evaluation order.

Example

package main

import (
	"context"
	"encoding/json/jsontext"
	"fmt"

	"github.com/rambow-cloud/powertools-lambda-go/validation"
)

func main() {
	schema, err := validation.Compile(context.Background(), jsontext.Value(`{
        "$schema":"https://json-schema.org/draft/2020-12/schema",
        "type":"array","prefixItems":[{"type":"integer"},{"type":"string"}],"items":false
    }`), validation.Options{Compiler: validation.Draft202012Compiler{}})
	if err != nil {
		panic(err)
	}
	_, valid := schema.Validate(context.Background(), []any{1, "ok"})
	_, extra := schema.Validate(context.Background(), []any{1, "ok", true})
	fmt.Println(valid == nil, extra != nil)
}

Output:
true true

func (Draft202012Compiler) Compile

func (Draft202012Compiler) Compile(ctx context.Context, input any, options CompileOptions) (Validator, error)

type Issue

type Issue struct {
	InstancePath string         `json:"instancePath"`
	SchemaPath   string         `json:"schemaPath"`
	Keyword      string         `json:"keyword"`
	Message      string         `json:"message"`
	Params       map[string]any `json:"params"`
	PropertyName *string        `json:"propertyName,omitzero"`
}

type Options

type Options struct {
	CompileOptions
	Envelope     string
	QueryOptions []jmespath.Option
	Compiler     Compiler
}

type RegexError

type RegexError struct {
	Pattern string
	Err     error
}

RegexError identifies an operational match failure, not an invalid payload.

func (*RegexError) Error

func (e *RegexError) Error() string

func (*RegexError) Unwrap

func (e *RegexError) Unwrap() error

type RegexOptions

type RegexOptions struct {
	MatchTimeout time.Duration
	// A positive value sets the stack bound; a negative value removes it.
	MaxBacktrackingStackSize int
}

RegexOptions configures operational limits without changing pattern syntax. Zero values use the engine's defaults: no timeout and a 100,000-entry stack.

type Schema

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

Schema retains a reusable validator and optional compiled extraction expression.

func Compile

func Compile(ctx context.Context, schema any, options Options) (*Schema, error)

Example

package main

import (
	"context"
	"fmt"

	"github.com/rambow-cloud/powertools-lambda-go/validation"
)

func main() {
	ctx := context.Background()
	schema, err := validation.Compile(ctx, map[string]any{
		"type": "object", "required": []any{"orderId"},
		"properties": map[string]any{"orderId": map[string]any{"type": "string"}},
	}, validation.Options{})
	if err != nil {
		panic(err)
	}
	value, err := schema.Validate(ctx, map[string]any{"orderId": "order-123"})
	if err != nil {
		panic(err)
	}
	fmt.Println(value.(map[string]any)["orderId"])
}

Output:
order-123

func (*Schema) Validate

func (s *Schema) Validate(ctx context.Context, payload any) (any, error)

type SchemaCompilationError

type SchemaCompilationError struct{ Err error }

func (*SchemaCompilationError) Error

func (e *SchemaCompilationError) Error() string

func (*SchemaCompilationError) Unwrap

func (e *SchemaCompilationError) Unwrap() error

type SchemaValidationError

type SchemaValidationError struct {
	Message string
	Issues  []Issue
	Err     error
}

func (*SchemaValidationError) Error

func (e *SchemaValidationError) Error() string

func (*SchemaValidationError) Unwrap

func (e *SchemaValidationError) Unwrap() error

type Validator

type Validator interface {
	Validate(context.Context, any) ([]Issue, error)
}

Validator returns validation diagnostics separately from operational errors. Implementations reused across invocations must support concurrent calls.

type ValidatorFunc

type ValidatorFunc func(context.Context, any) ([]Issue, error)

func (ValidatorFunc) Validate

func (f ValidatorFunc) Validate(ctx context.Context, input any) ([]Issue, error)