jsonschema

package
v0.11.8 Latest Latest
Warning

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

Go to latest
Published: Jul 13, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package jsonschema provides JSON Schema conversion for GoZod schemas.

Index

Constants

View Source
const (
	UnrepresentableThrow UnrepresentableMode = "throw"
	UnrepresentableAny   UnrepresentableMode = "any"

	CyclesRef   CyclesMode = "ref"
	CyclesThrow CyclesMode = "throw"

	ReusedInline ReusedMode = "inline"
	ReusedRef    ReusedMode = "ref"

	TargetDraft202012 TargetMode = "draft-2020-12"

	IOOutput IOMode = "output"
	IOInput  IOMode = "input"
)

Supported JSON Schema export option values.

Variables

View Source
var (
	ErrUnsupportedJSONSchemaType    = errors.New("unsupported JSON Schema type")
	ErrUnsupportedJSONSchemaKeyword = errors.New("unsupported JSON Schema keyword")
	ErrInvalidJSONSchema            = errors.New("invalid JSON Schema")
	ErrJSONSchemaCircularRef        = errors.New("circular reference detected in JSON Schema")
	ErrJSONSchemaPatternCompile     = errors.New("failed to compile JSON Schema pattern")
	ErrJSONSchemaIfThenElse         = errors.New("if/then/else is not supported")
	ErrJSONSchemaPatternProperties  = errors.New("patternProperties is not supported")
	ErrJSONSchemaDynamicRef         = errors.New("$dynamicRef is not supported")
	ErrJSONSchemaUnevaluatedProps   = errors.New("unevaluatedProperties is not supported")
	ErrJSONSchemaUnevaluatedItems   = errors.New("unevaluatedItems is not supported")
	ErrJSONSchemaDependentSchemas   = errors.New("dependentSchemas is not supported")
	ErrJSONSchemaPropertyNames      = errors.New("propertyNames is not supported")
	ErrJSONSchemaContains           = errors.New("contains/minContains/maxContains is not supported")
)

Conversion errors for FromJSONSchema operations.

View Source
var (
	ErrUnsupportedInputType          = errors.New("unsupported input type")
	ErrCircularReference             = errors.New("circular reference detected")
	ErrUnrepresentableType           = errors.New("unrepresentable type")
	ErrSchemaNotObjectOrStruct       = errors.New("schema is not a ZodObject or ZodStruct")
	ErrSliceElementNotSchema         = errors.New("slice element is not a ZodSchema")
	ErrArrayItemNotSchema            = errors.New("array item is not a ZodSchema")
	ErrUnhandledArrayLike            = errors.New("unhandled array-like type")
	ErrUnionInvalid                  = errors.New("schema is not a union type with Options method")
	ErrUnionNoMembers                = errors.New("union has no member schemas")
	ErrIntersectionInvalid           = errors.New("schema is not an intersection type")
	ErrInvalidEnumSchema             = errors.New("invalid enum schema")
	ErrEnumExtractValues             = errors.New("unable to extract enum values")
	ErrLiteralNoValuesMethod         = errors.New("schema does not have a Values method")
	ErrLiteralUnexpectedReturnValues = errors.New("unexpected number of return values from Values method")
	ErrExpectedDiscriminatedUnion    = errors.New("expected a discriminated union schema")
	ErrExpectedRecord                = errors.New("expected a record schema with ValueType()")
	ErrRecordValueNotSchema          = errors.New("record value type is not a valid schema")
	ErrInvalidRegistrySchemaID       = errors.New("invalid registry schema ID")
	ErrMapNoMethods                  = errors.New("schema does not implement KeyType() and ValueType() methods for map conversion")
	ErrMapKeyNotSchema               = errors.New("map key type is not a valid schema")
	ErrMapValueNotSchema             = errors.New("map value type is not a valid schema")
	ErrInvalidJSONSchemaOption       = errors.New("invalid JSON Schema option")
	ErrUnsupportedJSONSchemaTarget   = errors.New("unsupported JSON Schema target")
)

Conversion errors for ToJSONSchema operations.

Functions

func FromJSONSchema

func FromJSONSchema(schema *lib.Schema, opts ...FromJSONSchemaOptions) (core.ZodSchema, error)

FromJSONSchema converts a kaptinlin/jsonschema Schema to a GoZod schema. Returns core.ZodSchema for maximum flexibility.

func ToJSONSchema

func ToJSONSchema(input any, opts ...Options) (*lib.Schema, error)

ToJSONSchema converts a GoZod schema or registry into a JSON Schema instance.

Types

type CyclesMode added in v0.11.7

type CyclesMode string

CyclesMode controls how export handles cyclic schema graphs.

type FromJSONSchemaOptions

type FromJSONSchemaOptions struct {
	// Metadata receives imported JSON Schema metadata. Nil stores metadata on
	// the returned schema.
	Metadata *core.Registry[core.GlobalMeta]
}

FromJSONSchemaOptions configures the JSON Schema to GoZod conversion.

type IOMode added in v0.11.7

type IOMode string

IOMode selects whether export represents schema input or output shape.

type ImportError added in v0.11.8

type ImportError struct {
	Keyword string
	Pointer string
	Err     error
}

ImportError identifies the JSON Schema keyword and RFC 6901 location that failed to import.

func (*ImportError) Error added in v0.11.8

func (e *ImportError) Error() string

func (*ImportError) Unwrap added in v0.11.8

func (e *ImportError) Unwrap() error

Unwrap preserves sentinel and dependency error inspection.

type ImportLossError added in v0.11.8

type ImportLossError struct {
	Keyword string
	Pointer string
	Err     error
}

ImportLossError describes validation semantics intentionally omitted by a lossy import.

func FromJSONSchemaLossy added in v0.11.8

func FromJSONSchemaLossy(
	schema *lib.Schema,
	opts ...FromJSONSchemaOptions,
) (core.ZodSchema, []ImportLossError, error)

FromJSONSchemaLossy converts a JSON Schema while reporting omitted validation semantics.

func (ImportLossError) Error added in v0.11.8

func (l ImportLossError) Error() string

func (ImportLossError) Unwrap added in v0.11.8

func (l ImportLossError) Unwrap() error

Unwrap preserves sentinel and typed cause inspection.

type Options

type Options struct {
	// Metadata provides whole-record overrides for schemas present in the registry.
	// Schemas absent from the registry use their schema-owned metadata.
	Metadata *core.Registry[core.GlobalMeta]

	// How to handle unrepresentable types:
	// "throw" (default) - Unrepresentable types throw an error.
	// "any" - Unrepresentable types become {}.
	Unrepresentable UnrepresentableMode

	// How to handle cycles:
	// "ref" (default) - Cycles will be broken using $defs.
	// "throw" - Cycles will throw an error if encountered.
	Cycles CyclesMode

	// How to handle reused schemas:
	// "inline" (default) - Reused schemas will be inlined.
	// "ref" - Reused schemas will be extracted as $defs.
	Reused ReusedMode

	// A function used to convert ID values to URIs for external $refs.
	URI func(id string) string

	// Target specifies the JSON Schema version.
	// "draft-2020-12" (default).
	Target TargetMode

	// Override is a custom logic to modify the schema after generation.
	Override func(ctx OverrideContext)

	// IO specifies whether to convert the "input" or "output" schema.
	// "output" (default) or "input".
	IO IOMode
}

Options defines the configuration options for JSON schema conversion.

type OverrideContext

type OverrideContext struct {
	ZodSchema  core.ZodSchema
	JSONSchema *lib.Schema
}

OverrideContext provides context for the Override function.

type ReusedMode added in v0.11.7

type ReusedMode string

ReusedMode controls how export handles reused schema instances.

type TargetMode added in v0.11.7

type TargetMode string

TargetMode identifies the JSON Schema dialect emitted by export.

type UnrepresentableMode added in v0.11.7

type UnrepresentableMode string

UnrepresentableMode controls how export handles schemas with no faithful JSON Schema representation.

Jump to

Keyboard shortcuts

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