schema

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 20 Imported by: 0

README

schema

JSON Schema builders and validation without code generation, a Go port of Pi's @earendil-works/pi-schema (packages/schema). A schema compiles once into plain closures, so a value checks fast. Dependencies: github.com/dlclark/regexp2 for pattern (through schema/internal/ecmaregex) and golang.org/x/text for the internationalized format checks.

  • Drafts 2020-12 and 7. The vendored official JSON-Schema-Test-Suite gives the same pass and fail result for every case as Pi's package (TestConformanceSuite), including the nine tests Pi lists as known failures.
  • Builders return plain JSON Schema objects.
  • Errors are JSON Pointer paths. A missing or unknown field is reported at the field. The errors, their order and their messages equal Pi's (TestErrorsMatchPi).
  • A schema is read, never modified.
  • Check is the fast path: a boolean, no allocation for a schema without pattern or format. Errors explains a failure and returns nothing for a valid value. It is built on the first failure and kept.
  • Format checks are an optional import (schema/formats; every format 2020-12 defines, plus url and json-pointer-uri-fragment, which TypeBox and ajv-formats also check); without them format is an annotation, as 2020-12 specifies.
  • CompileCoercing adds Coerce and Parse for loosely typed input such as a model's tool call arguments: the results equal Pi's (TestCoerceMatchesPi, Pi's coerce.test.ts and TypeBox Value.Convert cases), copy-on-write, and no allocation for a value that needs no change.

Usage

import (
	"github.com/MichaelKinsy/PiG/schema"
	"github.com/MichaelKinsy/PiG/schema/formats"
)

read, err := schema.Compile(schema.Obj(schema.Properties{
	schema.Prop("path", schema.Str(schema.Description("Path to the file"), schema.MinLength(1))),
	schema.Opt("offset", schema.Int(schema.Minimum(1))),
	schema.Prop("mode", schema.OneOf([]any{"text", "binary"})),
}), schema.CompileOptions{Formats: formats.Formats()})

ok, err := read.Check(value)    // bool
errs, err := read.Errors(value) // []ValidationError{{Path: "/path", Keyword: "required", Message: "missing"}, ...}

Compile takes any JSON Schema (a bool, an *Object or a map[string]any), built with the builders or not, and returns an error for a malformed schema or a $ref that names nothing. With CompileOptions{UnresolvedRefs: schema.UnresolvedRefsReject} such a $ref compiles as false instead: only values at that place fail, with the error unresolved reference <ref>, and the rest of the schema works. Use it for schemas from other systems, such as MCP servers, whose references may dangle.

Check and Errors return an error only where Pi's check and errors throw: a part of the schema that Compile never compiled and that is malformed or names nothing (a $dynamicRef target compiled on first use; an if that is neither an object nor a boolean, read by the explanation). No panic leaves the package for a schema Compile accepted.

Values

JSON data is nil, bool, float64 (every Go numeric kind reads as a number), string, []any, *Object and map[string]any. []byte is Pi's Uint8Array: { "type": "bytes", "minLength": 1, "maxLength": 4 } matches a byte slice of that length.

*Object keeps JavaScript's property order, so builders and Errors order fields as Pi does. A Go map has no order; its keys are read in own-key order (array-index keys ascending, then the rest ascending).

Strings are UTF-8; a lone UTF-16 surrogate is held as WTF-8, as internal/jsstring holds it, and counts as one code point, matches . in a pattern and is escaped as \\uD800 in messages, as in JavaScript. A Go value has no undefined: an absent member is absent.

Builders

Str, Num, Int, Bool, Nul, Unknown, Lit, OneOf, Obj (with Prop, Opt, Open), Arr, Tuple, Map, Union, Nullable and Bytes return the same JSON Schema as Pi's builders, member order included. Options are applied in call order, as the members of the options object Pi's builders spread are, so Str(Description("d"), MinLength(1)) and Str(MinLength(1), Description("d")) write their members in that order. Each builder takes the options that fit its type, and a misplaced option does not compile (Str(MinItems(1)), Num(Open())):

option builders
Title, Description, Examples, Deprecated, Default every builder
MinLength, MaxLength Str, Bytes
Pattern, Format Str
Minimum, Maximum, ExclusiveMinimum, ExclusiveMaximum, MultipleOf Num, Int
MinItems, MaxItems, UniqueItems Arr
Open Obj

A Default is an annotation; validation never inserts it. Obj takes its properties as a Properties slice in declaration order; its properties and required follow JavaScript's own-key order (array-index names first), as Pi's obj() reads Object.entries.

The static types of Pi's builders (Static<S>) are TypeScript compile-time types and have no Go form.

Coercion

CompileCoercing(schema, options) returns a *CoercingValidator: a Validator that also has Coerce and Parse, for loosely typed input such as a model's tool call arguments (Pi's compile(schema, { coerce: true })). A plain Validator has neither, and its Check pays nothing for them: the coercion rules are built on the first Coerce or Parse.

read, err := schema.CompileCoercing(readSchema, schema.CompileOptions{})

value, err := read.Coerce(args) // {"path": "a.txt", "offset": "10"} becomes {"path": "a.txt", "offset": 10}

result, err := read.Parse(args) // ParseResult{OK, Value, Errors}
if result.OK {
	use(result.Value)
} else {
	show(result.Errors) // [{Path: "/offset", Keyword: "type", Message: "expected integer, got string"}]
}

Coerce(value) returns the coerced value. It copies only the paths it changes (an *Object or map[string]any keeps its member order in the copy), returns value itself when nothing changes, and never modifies value. A value no rule applies to stays as it is. Parse(value) coerces, then checks: ParseResult{OK: true, Value} with the coerced value, or ParseResult{Errors} with the errors of the coerced value. The errors returned are those Check and Errors return.

Three passes run in order:

  1. Optional nulls. A null in an optional property whose schema rejects null is dropped, as if omitted.
  2. Conversions, ported from TypeBox 1.3.27's Value.Convert and keyed on JSON Schema keywords (the first that applies to a schema): $ref follows the reference; const and enum take the member the value converts to; anyOf/oneOf keep a value one branch accepts, else take the first branch's conversion the whole schema accepts; allOf converts with each member in turn; then by type:
    • string: numbers and booleans to their text, null to "null".
    • number: numeric strings ("" is 0), "true"/"false", booleans to 1/0, null to 0.
    • integer: as number, then truncated ("3.5" and 3.5 become 3).
    • boolean: "true"/"false" (any case), "1"/"0", 1/0, null to false.
    • null: "null", "undefined", "", "0", 0 and false.
    • array: a single value becomes a one-item array, then each item converts; a tuple (prefixItems or an items array) converts its items and never wraps.
    • object: each property converts by properties, patternProperties or additionalProperties.
  3. Primitive coercion by type, as Ajv's coerceTypes, for what pass 2 leaves (type arrays such as ["integer", "null"]): numbers from numeric strings and booleans, booleans from "true"/"false" and 1/0, strings from numbers and booleans, null from "", 0 and false, and null to "", 0 or false. A value that already has one of a type array's types stays.

Where passes 2 and 3 disagree, pass 2 wins: null for a required string becomes "null", not "". A union's branches convert in order and only until one is accepted; a union node that also declares properties converts them into each branch's candidate before checking it. A recursive schema (a tree through $ref) that meets a value it cannot convert leaves the value as it is, so Check reports it, and results through a $ref are reused within one call, so a recursive union does not convert the same child once per branch.

Pass 1 drops optional nulls inside the values of properties, patternProperties and additionalProperties alike; a pattern or additional key itself is never dropped. Items past a draft-7 items array (additionalItems) are not coerced by any pass.

What a string reads as is JavaScript's: a number is what +value gives (" 1 ", "0x1F", "1e3" and "\u00a01" are numbers; "1_000" and "Infinity" are not), a trim removes JavaScript whitespace, and "any case" is toLowerCase. A Go value has no undefined and no bigint, so the conversions of those have no Go form; the string forms "12n" and "12.5" still read as a safe integer for a number, as in Pi.

Concurrency

A Validator is safe for concurrent use. A validator whose schema has a bookended $dynamicRef tracks the dynamic scope in state a check mutates, so its checks run one at a time.

A CoercingValidator is safe for concurrent use too. The state of one Coerce call is its own, so calls run in parallel; what they share (the compiler of the checks a union conversion asks for, the parsed keywords of each schema node) is built on first use under a lock. A Coerce of a value that needs no change allocates nothing. For a schema with a bookended $dynamicRef, the checks Coerce asks for run one at a time, as Check does.

Regular expressions

pattern and patternProperties are ECMAScript regular expressions with the u flag, as in Pi; a source that is invalid with it compiles without it. schema/internal/ecmaregex translates them into github.com/dlclark/regexp2 syntax.

Not supported

As in Pi: meta-schemas that switch vocabularies on or off ($vocabulary), contentMediaType and contentEncoding assertions, and draft 2019-09's $recursiveRef.

Benchmarks

go test ./schema -run '^$' -bench . -benchmem ports Pi's speed, setup and memory benchmarks (test/bench) over the same cases and a corpus generator verified against Pi's output. The comparison with other libraries, the bundle size and the no-eval run have no Go counterpart.

Documentation

Overview

Package schema validates JSON values against JSON Schema drafts 2020-12 and 7 without code generation: Compile builds a schema once into closures, and the builders return plain JSON Schema objects.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnnotationOption

type AnnotationOption interface {
	StrOption
	NumberOption
	ArrayOption
	BytesOption
	ObjectOption
	// contains filtered or unexported methods
}

AnnotationOption is an option every builder accepts: it describes the schema and never changes what it accepts. It satisfies every builder's option type.

func Default

func Default(value any) AnnotationOption

Default sets `default`, an annotation for tools and forms: validation never inserts it.

func Deprecated

func Deprecated(deprecated bool) AnnotationOption

Deprecated sets `deprecated`.

func Description

func Description(text string) AnnotationOption

Description sets `description`.

func Examples

func Examples(values ...any) AnnotationOption

Examples sets `examples`.

func Title

func Title(text string) AnnotationOption

Title sets `title`.

type ArrayOption

type ArrayOption interface {
	// contains filtered or unexported methods
}

ArrayOption is an option of Arr.

func MaxItems

func MaxItems(n int) ArrayOption

MaxItems sets `maxItems` of an array.

func MinItems

func MinItems(n int) ArrayOption

MinItems sets `minItems` of an array.

func UniqueItems

func UniqueItems(unique bool) ArrayOption

UniqueItems sets `uniqueItems` of an array.

type BytesOption

type BytesOption interface {
	// contains filtered or unexported methods
}

BytesOption is an option of Bytes.

type Check

type Check func(value any) bool

Check is a compiled boolean check.

type CoercingValidator

type CoercingValidator struct {
	*Validator
	// contains filtered or unexported fields
}

CoercingValidator is a Validator that also coerces loosely typed input towards the schema. It is safe for concurrent use.

func CompileCoercing

func CompileCoercing(schema JsonSchema, options CompileOptions) (*CoercingValidator, error)

CompileCoercing compiles schema into a CoercingValidator: a Validator that also coerces and parses loosely typed input (Pi's `compile(schema, { coerce: true })`). It fails where Compile does.

func (*CoercingValidator) Coerce

func (v *CoercingValidator) Coerce(value any) (any, error)

Coerce returns value coerced towards the schema: numeric strings to numbers, "true" to true, a single value to a one-item array, an optional null dropped, the first union branch the value converts to (the README lists every rule). Only the changed paths are copied; value comes back itself when nothing changes, and is never modified. Values that cannot be coerced stay as they are. The rules are built on the first call. The error is the one Pi's `coerce` throws: a pattern of the schema that is not a regular expression, or a dynamic reference that cannot be compiled, in a part of the schema the check never compiled.

func (*CoercingValidator) Parse

func (v *CoercingValidator) Parse(value any) (ParseResult, error)

Parse coerces value, then checks it: the coerced value when it is valid, else its errors.

type CompileOptions

type CompileOptions struct {
	// Draft is the draft whose semantics apply: Draft202012 (default, also for "") or Draft7.
	Draft Draft
	// Formats maps a format name to its check. Without it `format` is an annotation, as draft 2020-12 specifies. The standard formats are in package formats.
	Formats map[string]FormatCheck
	// Schemas holds schema documents by URI, for `$ref`s to other documents.
	Schemas map[string]JsonSchema
	// UnresolvedRefs is what a `$ref` that names nothing (a missing definition, a document not in Schemas) does: UnresolvedRefsThrow (default, also for "") makes Compile fail; UnresolvedRefsReject compiles it as `false`, so only values at that place fail, with the error "unresolved reference".
	UnresolvedRefs UnresolvedRefs
}

CompileOptions are the options of Compile.

type Draft

type Draft string

Draft is the draft whose semantics apply.

const (
	// Draft202012 is draft 2020-12, the default.
	Draft202012 Draft = "2020-12"
	// Draft7 is draft 7.
	Draft7 Draft = "7"
)

type FormatCheck

type FormatCheck func(value string) bool

FormatCheck reports whether value has the format.

type JsonSchema

type JsonSchema = any

JsonSchema is a JSON Schema: a bool, an *Object or a map[string]any. Schemas come from tool definitions, MCP servers and other untrusted sources, so Compile reads every keyword defensively instead of trusting a static shape.

type LengthOption

type LengthOption interface {
	StrOption
	BytesOption
}

LengthOption is an option of Str and Bytes.

func MaxLength

func MaxLength(n int) LengthOption

MaxLength sets `maxLength` of a string, in code points, or of bytes, in bytes.

func MinLength

func MinLength(n int) LengthOption

MinLength sets `minLength` of a string, in code points, or of bytes, in bytes.

type NumberOption

type NumberOption interface {
	// contains filtered or unexported methods
}

NumberOption is an option of Num and Int.

func ExclusiveMaximum

func ExclusiveMaximum(n float64) NumberOption

ExclusiveMaximum sets `exclusiveMaximum` of a number.

func ExclusiveMinimum

func ExclusiveMinimum(n float64) NumberOption

ExclusiveMinimum sets `exclusiveMinimum` of a number.

func Maximum

func Maximum(n float64) NumberOption

Maximum sets `maximum` of a number.

func Minimum

func Minimum(n float64) NumberOption

Minimum sets `minimum` of a number.

func MultipleOf

func MultipleOf(n float64) NumberOption

MultipleOf sets `multipleOf` of a number.

type Object

type Object = chordjson.Object

Object is a JSON object that keeps JavaScript's property order (own keys: array-index keys ascending, then insertion order).

type ObjectOption

type ObjectOption interface {
	// contains filtered or unexported methods
}

ObjectOption is an option of Obj.

func Open

func Open() ObjectOption

Open lets an Obj schema allow properties it does not declare, as tool schemas from other systems often do.

type ParseResult

type ParseResult struct {
	OK     bool
	Value  any
	Errors []ValidationError
}

ParseResult is the result of CoercingValidator.Parse: the coerced Value when OK, else the Errors of the coerced value.

type Properties

type Properties []Property

Properties are the properties of Obj in declaration order. The `properties` and `required` of the schema, and so the order of its errors, follow JavaScript's own-key order: array-index names first in ascending order, then the others in declaration order. A name declared twice keeps its first position and its last declaration.

type Property

type Property struct {
	Name     string
	Schema   Schema
	Optional bool
}

Property is a property of Obj.

func Opt

func Opt(name string, schema Schema) Property

Opt is an optional property of Obj: `Opt("name", Str())` may be omitted.

func Prop

func Prop(name string, schema Schema) Property

Prop is a required property of Obj.

type Schema

type Schema = *Object

Schema is a JSON Schema object returned by a builder.

func Arr

func Arr(items Schema, options ...ArrayOption) Schema

Arr is an array of items, with optional length bounds and unique items.

func Bool

func Bool(options ...AnnotationOption) Schema

Bool is a boolean.

func Bytes

func Bytes(options ...BytesOption) Schema

Bytes is a []byte with optional length bounds (an extension of JSON Schema for values that never pass through JSON).

func Int

func Int(options ...NumberOption) Schema

Int is an integer within optional bounds.

func Lit

func Lit(value any, options ...AnnotationOption) Schema

Lit is exactly value (a string, number, boolean or nil).

func Map

func Map(value Schema, options ...AnnotationOption) Schema

Map is an object with string keys and values of value (a record).

func Nul

func Nul(options ...AnnotationOption) Schema

Nul is `null`.

func Nullable

func Nullable(schema Schema, options ...AnnotationOption) Schema

Nullable is schema or null.

func Num

func Num(options ...NumberOption) Schema

Num is a number within optional bounds.

func Obj

func Obj(properties Properties, options ...ObjectOption) Schema

Obj is a closed object: the given properties (required unless Opt) and no others. The Open option allows other properties, as tool schemas from other systems often do.

func OneOf

func OneOf(values []any, options ...AnnotationOption) Schema

OneOf is one of the given values.

func Str

func Str(options ...StrOption) Schema

Str is a string, with optional length bounds (in code points), pattern and format.

func Tuple

func Tuple(items []Schema, options ...AnnotationOption) Schema

Tuple is a fixed-length array whose items match items in order.

func Union

func Union(schemas []Schema, options ...AnnotationOption) Schema

Union is any of the given schemas. A union of objects tagged by a Lit property (`{ kind: Lit("text"), ... }`) is checked by the tag: only the branch it selects runs, and its errors are the ones reported.

func Unknown

func Unknown(options ...AnnotationOption) Schema

Unknown is any value.

type StrOption

type StrOption interface {
	// contains filtered or unexported methods
}

StrOption is an option of Str.

func Format

func Format(name string) StrOption

Format sets `format` of a string.

func Pattern

func Pattern(source string) StrOption

Pattern sets `pattern` of a string.

type UnresolvedRefs

type UnresolvedRefs string

UnresolvedRefs selects what a `$ref` that names nothing does.

const (
	// UnresolvedRefsThrow makes Compile fail.
	UnresolvedRefsThrow UnresolvedRefs = "throw"
	// UnresolvedRefsReject compiles the reference as `false`.
	UnresolvedRefsReject UnresolvedRefs = "reject"
)

type ValidationError

type ValidationError struct {
	Path    string
	Keyword string
	Message string
}

ValidationError is one failure of a value: where it is (a JSON Pointer, "" for the value itself), the failing keyword and a message.

type Validator

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

Validator is a compiled schema. It is safe for concurrent use.

A validator whose schema has a bookended `$dynamicRef` tracks the dynamic scope in state that a check mutates, and compiles the dynamic targets on first use, so its checks run one at a time.

func Compile

func Compile(schema JsonSchema, options CompileOptions) (*Validator, error)

Compile compiles schema into a Validator. It fails if the schema is malformed or a `$ref` names nothing (register other documents with options.Schemas). The schema is read, never modified.

func (*Validator) Check

func (v *Validator) Check(value any) (bool, error)

Check reports whether value is valid. The error is the one a `$dynamicRef` target that is malformed or names nothing raises when a check first reaches it, as that compile error does upstream; every other validator never fails.

func (*Validator) Errors

func (v *Validator) Errors(value any) ([]ValidationError, error)

Errors explains why value is invalid: one error per failing keyword, none when it is valid. The explanation is built on the first failure and kept, so a validator whose values always pass never pays for it. The error is the one the explanation raises where Pi's `errors` throws: a subschema that is neither an object nor a boolean, or a reference that names nothing, in a part of the schema the check never compiled.

Directories

Path Synopsis
Package formats holds the format checks of JSON Schema 2020-12, for the schema package's formats option.
Package formats holds the format checks of JSON Schema 2020-12, for the schema package's formats option.
internal/idna
Package idna validates hostnames and internationalized hostnames with Pi's own IDNA checks (RFC 5890, 5891, 5892, 5893).
Package idna validates hostnames and internationalized hostnames with Pi's own IDNA checks (RFC 5890, 5891, 5892, 5893).
internal
ecmaregex
Package ecmaregex runs ECMAScript regular expressions: the engine behind `new RegExp(source, "u")` and `new RegExp(source)` for patterns without the d, g, v and y flags, which is what packages/schema/src/shared.ts (sharedRegex) and packages/schema/src/formats/typebox/regex.ts construct.
Package ecmaregex runs ECMAScript regular expressions: the engine behind `new RegExp(source, "u")` and `new RegExp(source)` for patterns without the d, g, v and y flags, which is what packages/schema/src/shared.ts (sharedRegex) and packages/schema/src/formats/typebox/regex.ts construct.

Jump to

Keyboard shortcuts

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