walle

README

walle

A Moonshot AI flavored Json schema validator.

Entry Point

The main entry point is walle.go, which provides two core APIs:

• ParseSchema: Parses input JSON schema string and creates a walle schema instance
• Schema.Validate: Validates the schema with optional configurations
  • Three validation levels:
    • strict: Most comprehensive validation including potentially "harmless" checks (e.g., no duplicate items). Aligns with model training behavior.
    • lite: Semantic correctness validation. The most permissive level required by Moonshot AI server for efficient structured generation.
    • loose: Minimal validation that relies more on model capabilities. (Not recommended for production use)

Usage

cli

go install github.com/moonshotai/walle/cmd/walle@latest

walle -schema '{"type": "object"}' -level strict
walle -schema-file your_schema.json

go package

import "github.com/moonshotai/walle"

// Define your JSON schema
schemaStr := `{
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}`

// Create a schema instance
schema, err := walle.ParseSchema(schemaStr)
...

// Validate the schema with default options
err = schema.Validate()
...

// Validate the schema with custom options
err = schema.Validate(
    walle.WithValidateLevel(walle.ValidateLevelStrict),
)
...

Python

The Python interface provides a simple wrapper around the walle Go package. To use it, first build the shared library by running ./build.sh in the c-shared directory, then refer to the implementation in c-shared/walle.py for usage details.

Example:

from walle import WalleValidator

# Initialize validator
validator = WalleValidator()

# Validate a schema
schema = '''
{
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"}
    },
    "required": ["name"]
}
'''
validator.validate_schema(schema)
...

# With custom configuration
config = {
    "validateLevel": "strict",
    "maxEnumItems": 3
}
validator.validate_schema(schema, config)
...

Documentation

Index

• Constants
• Variables
• func IsSchemaError(err error) bool
• func IsUnmarshalError(err error) bool
• func NewSchemaError(message string, path string, simplifyFunc SimplifyFunc) error
• type KeywordValidatorFunc
• type Schema
  • func ParseSchema(jsonStr string) (Schema, error)
  • func SimplifyDefault(schema Schema, _ schemaPath) Schema
  • func SimplifyNegativeVal(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveAdditionalProperties(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveAnyOf(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveConstraints(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveDefs(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveDefsEmptySubSchema(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveDescription(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveDuplicateType(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveEnum(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveID(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveItems(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveParentSchema(schema Schema, path schemaPath) Schema
  • func SimplifyRemovePattern(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveProperties(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveRef(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveRequired(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveSubSchema(schema Schema, path schemaPath) Schema
  • func SimplifyRemoveType(schema Schema, path schemaPath) Schema
  • func (s Schema) Canonical() (string, error)
  • func (s Schema) Validate(options ...SchemaValidatorOption) error
• type SchemaDict
• type SchemaError
  • func (e *SchemaError) Error() string
• type SchemaList
• type SchemaValidatorConfig
  • func DefaultValidatorConfig() SchemaValidatorConfig
  • func (c *SchemaValidatorConfig) IsLite() bool
  • func (c *SchemaValidatorConfig) IsLoose() bool
  • func (c *SchemaValidatorConfig) IsStrict() bool
  • func (c *SchemaValidatorConfig) IsTest() bool
• type SchemaValidatorOption
  • func WithMaxAnyOfItems(max int) SchemaValidatorOption
  • func WithMaxEnumItems(max int) SchemaValidatorOption
  • func WithMaxEnumStringCheckThreshold(max int) SchemaValidatorOption
  • func WithMaxEnumStringLength(max int) SchemaValidatorOption
  • func WithMaxSchemaDepth(max int) SchemaValidatorOption
  • func WithMaxSchemaSize(max int) SchemaValidatorOption
  • func WithMaxTotalPropertiesKeysNum(max int) SchemaValidatorOption
  • func WithValidateLevel(level ValidateLevel) SchemaValidatorOption
• type SimplifyFunc
• type UnmarshalError
  • func NewUnmarshalError(err error) *UnmarshalError
  • func (e *UnmarshalError) Error() string
• type ValidateLevel

Constants

const (
	Type                 = "type"
	Properties           = "properties"
	AdditionalProperties = "additionalProperties"
	Items                = "items"
	Enum                 = "enum"
	Required             = "required"
	AnyOf                = "anyOf"
	Description          = "description"
	Defs                 = "$defs"
	Ref                  = "$ref"
	Title                = "title"
	Id                   = "$id"
	Default              = "default"
	Pattern              = "pattern"
	MaxLength            = "maxLength"
	MinLength            = "minLength"
	Maximum              = "maximum"
	Minimum              = "minimum"
	MaxItems             = "maxItems"
	MinItems             = "minItems"
	String               = "string"
	Number               = "number"
	Integer              = "integer"
	Boolean              = "boolean"
	Null                 = "null"
	Array                = "array"
	Object               = "object"
	Root                 = "root"
)

Variables

var (
	// Valid types and supported types
	ValidTypes = map[string]bool{
		"string":  true,
		"number":  true,
		"integer": true,
		"boolean": true,
		"null":    true,
		"array":   true,
		"object":  true,
	}

	// Common keywords
	CommonKeywords = map[string]bool{
		"description": true,
		"title":       true,
	}

	// Allowed keywords for different types
	ObjectAllowedKeywords = mergeMaps(map[string]bool{
		"type":                 true,
		"properties":           true,
		"required":             true,
		"additionalProperties": true,
		"$ref":                 true,
		"anyOf":                true,
		"default":              true,
	}, CommonKeywords)

	ArrayAllowedKeywords = mergeMaps(map[string]bool{
		"type":     true,
		"items":    true,
		"minItems": true,
		"maxItems": true,
		"$ref":     true,
		"default":  true,
	}, CommonKeywords)

	StringAllowedKeywords = mergeMaps(map[string]bool{
		"type":      true,
		"minLength": true,
		"maxLength": true,
		"pattern":   true,
		"enum":      true,
		"default":   true,
	}, CommonKeywords)

	BooleanAllowedKeywords = mergeMaps(map[string]bool{
		"type":    true,
		"enum":    true,
		"default": true,
	}, CommonKeywords)

	NullAllowedKeywords = mergeMaps(map[string]bool{
		"type":    true,
		"enum":    true,
		"default": true,
	}, CommonKeywords)

	NumberAllowedKeywords = mergeMaps(map[string]bool{
		"type":    true,
		"minimum": true,
		"maximum": true,
		"enum":    true,
		"default": true,
	}, CommonKeywords)

	TopLevelOnlyKeywords = map[string]bool{
		"$defs": true,
		"$id":   true,
	}

	// Contexts where $ref is allowed, "properties", "$defs", "root" will be processed independently
	RefAllowedContexts = map[string]bool{
		"additionalProperties": true,
		"anyOf":                true,
		"items":                true,
	}

	// currently supported keywords
	SupportedKeywords = map[string]bool{
		"type":                 true,
		"properties":           true,
		"additionalProperties": true,
		"items":                true,
		"enum":                 true,
		"required":             true,
		"anyOf":                true,
		"description":          true,
		"$defs":                true,
		"$ref":                 true,
		"title":                true,
		"$id":                  true,
		"default":              true,
	}

	// will be supported in the future
	FutureKeywords = map[string]bool{
		"maxLength": true,
		"minLength": true,
		"maximum":   true,
		"minimum":   true,
		"maxItems":  true,
		"minItems":  true,
		"pattern":   true,
	}

	InvalidPropertyNames = map[string]bool{
		"$defs":                true,
		"$ref":                 true,
		"anyOf":                true,
		"required":             true,
		"additionalProperties": true,
	}
)

Functions

func IsSchemaError

func IsSchemaError(err error) bool

func IsUnmarshalError

func IsUnmarshalError(err error) bool

func NewSchemaError

func NewSchemaError(message string, path string, simplifyFunc SimplifyFunc) error

Types

type KeywordValidatorFunc

type KeywordValidatorFunc func(any, *validationContext, schemaPath) error

type Schema

type Schema map[string]any

func ParseSchema

func ParseSchema(jsonStr string) (Schema, error)

func SimplifyDefault

func SimplifyDefault(schema Schema, _ schemaPath) Schema

func SimplifyNegativeVal

func SimplifyNegativeVal(schema Schema, path schemaPath) Schema

func SimplifyRemoveAdditionalProperties

func SimplifyRemoveAdditionalProperties(schema Schema, path schemaPath) Schema

func SimplifyRemoveAnyOf

func SimplifyRemoveAnyOf(schema Schema, path schemaPath) Schema

func SimplifyRemoveConstraints

func SimplifyRemoveConstraints(schema Schema, path schemaPath) Schema

func SimplifyRemoveDefs

func SimplifyRemoveDefs(schema Schema, path schemaPath) Schema

func SimplifyRemoveDefsEmptySubSchema

func SimplifyRemoveDefsEmptySubSchema(schema Schema, path schemaPath) Schema

func SimplifyRemoveDescription

func SimplifyRemoveDescription(schema Schema, path schemaPath) Schema

func SimplifyRemoveDuplicateType

func SimplifyRemoveDuplicateType(schema Schema, path schemaPath) Schema

func SimplifyRemoveEnum

func SimplifyRemoveEnum(schema Schema, path schemaPath) Schema

func SimplifyRemoveID

func SimplifyRemoveID(schema Schema, path schemaPath) Schema

func SimplifyRemoveItems

func SimplifyRemoveItems(schema Schema, path schemaPath) Schema

func SimplifyRemoveParentSchema

func SimplifyRemoveParentSchema(schema Schema, path schemaPath) Schema

func SimplifyRemovePattern

func SimplifyRemovePattern(schema Schema, path schemaPath) Schema

func SimplifyRemoveProperties

func SimplifyRemoveProperties(schema Schema, path schemaPath) Schema

func SimplifyRemoveRef

func SimplifyRemoveRef(schema Schema, path schemaPath) Schema

func SimplifyRemoveRequired

func SimplifyRemoveRequired(schema Schema, path schemaPath) Schema

func SimplifyRemoveSubSchema

func SimplifyRemoveSubSchema(schema Schema, path schemaPath) Schema

func SimplifyRemoveType

func SimplifyRemoveType(schema Schema, path schemaPath) Schema

func (Schema) Canonical

func (s Schema) Canonical() (string, error)

Canonical returns a schema representation that conforms to Moonshot AI server requirements. It uses `lite` validation level, which is the most permissive level supported by the server. If the original schema has issues, it returns a simplified schema.

func (Schema) Validate

func (s Schema) Validate(options ...SchemaValidatorOption) error

type SchemaDict

type SchemaDict = map[string]any

type SchemaError

type SchemaError struct {
	Path         string       `json:"path,omitempty"`
	Message      string       `json:"message,omitempty"`
	SimplifyFunc SimplifyFunc `json:"-"`
}

func (*SchemaError) Error

func (e *SchemaError) Error() string

type SchemaList

type SchemaList = []any

type SchemaValidatorConfig

type SchemaValidatorConfig struct {
	ValidateLevel               ValidateLevel `json:"validateLevel,omitempty"`
	MaxEnumItems                int           `json:"maxEnumItems,omitempty"`
	MaxEnumStringLength         int           `json:"maxEnumStringLength,omitempty"`
	MaxEnumStringCheckThreshold int           `json:"maxEnumStringCheckThreshold,omitempty"`
	MaxAnyOfItems               int           `json:"maxAnyOfItems,omitempty"`
	MaxSchemaDepth              int           `json:"maxSchemaDepth,omitempty"`
	MaxSchemaSize               int           `json:"maxSchemaSize,omitempty"`
	MaxTotalPropertiesKeysNum   int           `json:"maxTotalPropertiesKeysNum,omitempty"`
}

func DefaultValidatorConfig

func DefaultValidatorConfig() SchemaValidatorConfig

func (*SchemaValidatorConfig) IsLite

func (c *SchemaValidatorConfig) IsLite() bool

func (*SchemaValidatorConfig) IsLoose

func (c *SchemaValidatorConfig) IsLoose() bool

func (*SchemaValidatorConfig) IsStrict

func (c *SchemaValidatorConfig) IsStrict() bool

func (*SchemaValidatorConfig) IsTest

func (c *SchemaValidatorConfig) IsTest() bool

do not use in production

type SchemaValidatorOption

type SchemaValidatorOption func(*SchemaValidatorConfig)

func WithMaxAnyOfItems

func WithMaxAnyOfItems(max int) SchemaValidatorOption

WithMaxAnyOfItems set max anyOf items

func WithMaxEnumItems

func WithMaxEnumItems(max int) SchemaValidatorOption

WithMaxEnumItems set max enum items

func WithMaxEnumStringCheckThreshold

func WithMaxEnumStringCheckThreshold(max int) SchemaValidatorOption

WithMaxEnumStringCheckThreshold set max enum string check threshold

func WithMaxEnumStringLength

func WithMaxEnumStringLength(max int) SchemaValidatorOption

WithMaxEnumStringLength set max enum string length

func WithMaxSchemaDepth

func WithMaxSchemaDepth(max int) SchemaValidatorOption

WithMaxSchemaDepth set max schema depth

func WithMaxSchemaSize

func WithMaxSchemaSize(max int) SchemaValidatorOption

WithMaxSchemaSize set max schema size

func WithMaxTotalPropertiesKeysNum

func WithMaxTotalPropertiesKeysNum(max int) SchemaValidatorOption

WithMaxTotalPropertiesKeysNum set max total properties keys num

func WithValidateLevel

func WithValidateLevel(level ValidateLevel) SchemaValidatorOption

type SimplifyFunc

type SimplifyFunc func(schema Schema, path schemaPath) Schema

type UnmarshalError

type UnmarshalError struct {
	Err error `json:"error,omitempty"`
}

func NewUnmarshalError

func NewUnmarshalError(err error) *UnmarshalError

func (*UnmarshalError) Error

func (e *UnmarshalError) Error() string

type ValidateLevel

type ValidateLevel string

const (
	ValidateLevelDefault ValidateLevel = "default" // default == strict
	ValidateLevelLoose   ValidateLevel = "loose"
	ValidateLevelLite    ValidateLevel = "lite"
	ValidateLevelStrict  ValidateLevel = "strict"
	ValidateLevelTest    ValidateLevel = "test" // Do not use in production!
)