package jsonschema

import "golang.org/x/tools/internal/mcp/jsonschema"

Package jsonschema is an implementation of the JSON Schema specification: https://json-schema.org.

Index ¶

• func Equal(x, y any) bool
• func Ptr[T any](x T) *T
• type Resolved
• func (rs *Resolved) Validate(instance any) error
• type Schema
• func For[T any]() (*Schema, error)
• func ForType(t reflect.Type) (*Schema, error)
• func (s *Schema) MarshalJSON() ([]byte, error)
• func (root *Schema) Resolve() (*Resolved, error)
• func (s *Schema) String() string
• func (s *Schema) UnmarshalJSON(data []byte) error

Functions ¶

func Equal ¶

func Equal(x, y any) bool

Equal reports whether two Go values representing JSON values are equal according to the JSON Schema spec. The values must not contain cycles. See https://json-schema.org/draft/2020-12/json-schema-core#section-4.2.2. It behaves like reflect.DeepEqual, except that numbers are compared according to mathematical equality.

func Ptr ¶

func Ptr[T any](x T) *T

Ptr returns a pointer to a new variable whose value is x.

Types ¶

type Resolved ¶

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

A Resolved consists of a Schema along with associated information needed to validate documents against it. A Resolved has been validated against its meta-schema, and all its references (the $ref and $dynamicRef keywords) have been resolved to their referenced Schemas. Call Schema.Resolve to obtain a Resolved from a Schema.

func (*Resolved) Validate ¶

func (rs *Resolved) Validate(instance any) error

Validate validates the instance, which must be a JSON value, against the schema. It returns nil if validation is successful or an error if it is not.

type Schema ¶

type Schema struct {
	// core
	ID      string             `json:"$id,omitempty"`
	Schema  string             `json:"$schema,omitempty"`
	Ref     string             `json:"$ref,omitempty"`
	Comment string             `json:"$comment,omitempty"`
	Defs    map[string]*Schema `json:"$defs,omitempty"`
	// definitions is deprecated but still allowed. It is a synonym for $defs.
	Definitions map[string]*Schema `json:"definitions,omitempty"`

	Anchor        string          `json:"$anchor,omitempty"`
	DynamicAnchor string          `json:"$dynamicAnchor,omitempty"`
	DynamicRef    string          `json:"$dynamicRef,omitempty"`
	Vocabulary    map[string]bool `json:"$vocabulary,omitempty"`

	// metadata
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`

	// validation
	// Use Type for a single type, or Types for multiple types; never both.
	Type  string   `json:"-"`
	Types []string `json:"-"`
	Enum  []any    `json:"enum,omitempty"`
	// Const is *any because a JSON null (Go nil) is a valid value.
	Const            *any     `json:"const,omitempty"`
	MultipleOf       *float64 `json:"multipleOf,omitempty"`
	Minimum          *float64 `json:"minimum,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty"`
	ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitempty"`
	MinLength        *int     `json:"minLength,omitempty"`
	MaxLength        *int     `json:"maxLength,omitempty"`
	Pattern          string   `json:"pattern,omitempty"`

	// arrays
	PrefixItems      []*Schema `json:"prefixItems,omitempty"`
	Items            *Schema   `json:"items,omitempty"`
	MinItems         *int      `json:"minItems,omitempty"`
	MaxItems         *int      `json:"maxItems,omitempty"`
	AdditionalItems  *Schema   `json:"additionalItems,omitempty"`
	UniqueItems      bool      `json:"uniqueItems,omitempty"`
	Contains         *Schema   `json:"contains,omitempty"`
	MinContains      *int      `json:"minContains,omitempty"` // *int, not int: default is 1, not 0
	MaxContains      *int      `json:"maxContains,omitempty"`
	UnevaluatedItems *Schema   `json:"unevaluatedItems,omitempty"`

	// objects
	MinProperties         *int                `json:"minProperties,omitempty"`
	MaxProperties         *int                `json:"maxProperties,omitempty"`
	Required              []string            `json:"required,omitempty"`
	DependentRequired     map[string][]string `json:"dependentRequired,omitempty"`
	Properties            map[string]*Schema  `json:"properties,omitempty"`
	PatternProperties     map[string]*Schema  `json:"patternProperties,omitempty"`
	AdditionalProperties  *Schema             `json:"additionalProperties,omitempty"`
	PropertyNames         *Schema             `json:"propertyNames,omitempty"`
	UnevaluatedProperties *Schema             `json:"unevaluatedProperties,omitempty"`

	// logic
	AllOf []*Schema `json:"allOf,omitempty"`
	AnyOf []*Schema `json:"anyOf,omitempty"`
	OneOf []*Schema `json:"oneOf,omitempty"`
	Not   *Schema   `json:"not,omitempty"`

	// conditional
	If               *Schema            `json:"if,omitempty"`
	Then             *Schema            `json:"then,omitempty"`
	Else             *Schema            `json:"else,omitempty"`
	DependentSchemas map[string]*Schema `json:"dependentSchemas,omitempty"`
	// contains filtered or unexported fields
}

A Schema is a JSON schema object. It corresponds to the 2020-12 draft, as described in https://json-schema.org/draft/2020-12, specifically: - https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-01 - https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-01

A Schema value may have non-zero values for more than one field: all relevant non-zero fields are used for validation. There is one exception to provide more Go type-safety: the Type and Types fields are mutually exclusive.

Since this struct is a Go representation of a JSON value, it inherits JSON's distinction between nil and empty. Nil slices and maps are considered absent, but empty ones are present and affect validation. For example,

Schema{Enum: nil}

is equivalent to an empty schema, so it validates every instance. But

Schema{Enum: []any{}}

requires equality to some slice element, so it vacuously rejects every instance.

func For ¶

func For[T any]() (*Schema, error)

For constructs a JSON schema object for the given type argument.

It is a convenience for ForType.

func ForType ¶

func ForType(t reflect.Type) (*Schema, error)

ForType constructs a JSON schema object for the given type. It translates Go types into compatible JSON schema types, as follows:

• strings have schema type "string"
• bools have schema type "boolean"
• signed and unsigned integer types have schema type "integer"
• floating point types have schema type "number"
• slices and arrays have schema type "array", and a corresponding schema for items
• maps with string key have schema type "object", and corresponding schema for additionalProperties
• structs have schema type "object", and disallow additionalProperties. Their properties are derived from exported struct fields, using the struct field json name. Fields that are marked "omitempty" are considered optional; all other fields become required properties.

It returns an error if t contains (possibly recursively) any of the following Go types, as they are incompatible with the JSON schema spec.

• maps with key other than 'string'
• function types
• complex numbers
• unsafe pointers

TODO(rfindley): we could perhaps just skip these incompatible fields.

func (*Schema) MarshalJSON ¶

func (s *Schema) MarshalJSON() ([]byte, error)

func (*Schema) Resolve ¶

func (root *Schema) Resolve() (*Resolved, error)

Resolve resolves all references within the schema and performs other tasks that prepare the schema for validation.

func (*Schema) String ¶

func (s *Schema) String() string

String returns a short description of the schema.

func (*Schema) UnmarshalJSON ¶

func (s *Schema) UnmarshalJSON(data []byte) error

Source Files ¶

annotations.go infer.go resolve.go schema.go util.go validate.go