Skip to content
go-gen-jsonschema

API Reference

jsonschema

Section titled “jsonschema”
import "github.com/tylergannon/go-gen-jsonschema"

Index

Section titled “Index”

type DataType

Section titled “type DataType”
type DataType string

const (
    Object  DataType = "object"
    Number  DataType = "number"
    Integer DataType = "integer"
    String  DataType = "string"
    Array   DataType = "array"
    Null    DataType = "null"
    Boolean DataType = "boolean"
)

type EnumType

Section titled “type EnumType”
type EnumType struct{}

func NewEnumType

Section titled “func NewEnumType”
func NewEnumType[T ~string]() EnumType

NewEnumType denotes that the type argument should be an enum. If called in the same package where the type is declared, then it applies globally. In all cases, the const values MUST be declared in the same package as the call to NewEnumType.

For now, only string types are supported.

type InterfaceMarker

Section titled “type InterfaceMarker”
type InterfaceMarker struct{}

func NewInterfaceImpl

Section titled “func NewInterfaceImpl”
func NewInterfaceImpl[T any](...T) InterfaceMarker

NewInterfaceImpl marks the arguments as possible implementations for the interface type given in the type argument.

  1. If called in the same package as the interface itself, then all global instances can be replaced.
  2. If called somewhere else, only applies to the local package.

type InterfaceOption

Section titled “type InterfaceOption”

InterfaceOption configures a registered interface field.

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

func Discriminator

Section titled “func Discriminator”
func Discriminator(name string) InterfaceOption

Discriminator sets the JSON property used to distinguish interface cases.

func Impl

Section titled “func Impl”
func Impl[T any](value string, impl T) InterfaceOption

Impl registers an interface implementation with its stable wire value.

type InterfaceOptionObj

Section titled “type InterfaceOptionObj”
type InterfaceOptionObj struct{}

type JSONSchema

Section titled “type JSONSchema”

JSONSchema is a struct for describing a JSON Schema. It is fairly limited, and you may have better luck using a third-party library. This is a copy from go-openai’s “jsonschema.Definition{}” struct, with the difference being that this one holds references to json.Marshaler, rather than to itself.

type JSONSchema struct {
    // Type specifies the data type of the schema.
    Type DataType `json:"type" yaml:"type"`
    // Description is the description of the schema.
    Description string `json:"description,omitempty" yaml:"description,omitempty"`
    // Enum is used to restrict a value to a fixed set of values. It must be an
    // array with at least one element, where each element is unique. You will
    // probably only use this with strings.
    Enum []any `json:"enum,omitempty" yaml:"enum,omitempty"`
    // Properties describes the properties of an object, if the schema type is
    // Object.
    Properties map[string]SchemaNode `json:"properties,omitempty" yaml:"properties,omitempty"`
    // Required specifies which properties are required, if the schema type is
    // Object.
    Required []string `json:"required,omitempty" yaml:"required,omitempty"`
    // Items specifies which data type an array contains, if the schema type is
    // Array.
    Items SchemaNode `json:"items,omitempty" yaml:"items,omitempty"`
    // AdditionalProperties is used to control the handling of properties in an
    // object that are not explicitly defined in the properties section of the
    // schema. example: additionalProperties: true additionalProperties: false
    // additionalProperties: jsonschema.Definition{Type: jsonschema.String}
    AdditionalProperties any                   `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
    Definitions          map[string]SchemaNode `json:"$defs,omitzero" yaml:"$defs,omitempty"`
    Const                any                   `json:"const,omitempty"` // Provide a const value
    // Strict will make all properties required and additionalProperties: false if
    // not already set. pplies only if Type = "object".
    Strict bool `json:"-" yaml:"-"`
}

func (JSONSchema) MarshalJSON

Section titled “func (JSONSchema) MarshalJSON”
func (s JSONSchema) MarshalJSON() ([]byte, error)

type JSONUnionType

Section titled “type JSONUnionType”
type JSONUnionType []*JSONSchema

func (JSONUnionType) MarshalJSON

Section titled “func (JSONUnionType) MarshalJSON”
func (j JSONUnionType) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type Nullable

Section titled “type Nullable”

Nullable represents a required object property whose value may be null. The zero value encodes as null; Present reports whether Value is non-null.

type Nullable[T any] struct {
    Present bool
    Value   T
}

func (Nullable[T]) IsZero

Section titled “func (Nullable[T]) IsZero”
func (Nullable[T]) IsZero() bool

IsZero always reports false so json:“,omitzero” cannot omit a required nullable property.

func (Nullable[T]) MarshalJSON

Section titled “func (Nullable[T]) MarshalJSON”
func (n Nullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes null or a present non-null value.

func (*Nullable[T]) UnmarshalJSON

Section titled “func (*Nullable[T]) UnmarshalJSON”
func (n *Nullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes null or a present value without mutating the receiver when decoding fails.

type ObjectSchema

Section titled “type ObjectSchema”
type ObjectSchema struct {
    Properties           []SchemaProperty
    Strict               bool
    Required             []string
    Description          string
    AdditionalProperties any
}

func (*ObjectSchema) AddProperty

Section titled “func (*ObjectSchema) AddProperty”
func (s *ObjectSchema) AddProperty(key string, value SchemaNode)

func (*ObjectSchema) AddRequiredProperty

Section titled “func (*ObjectSchema) AddRequiredProperty”
func (s *ObjectSchema) AddRequiredProperty(key string, value SchemaNode)

func (ObjectSchema) MarshalJSON

Section titled “func (ObjectSchema) MarshalJSON”
func (s ObjectSchema) MarshalJSON() ([]byte, error)

type Optional

Section titled “type Optional”

Optional represents an object property that may be absent. The zero value is absent; a present value may contain T’s zero value but may not encode as null. Containing struct fields must use json:“,omitzero” so absent values are omitted before MarshalJSON is called.

type Optional[T any] struct {
    Present bool
    Value   T
}

func (Optional[T]) IsZero

Section titled “func (Optional[T]) IsZero”
func (o Optional[T]) IsZero() bool

IsZero reports whether the property is absent.

func (Optional[T]) MarshalJSON

Section titled “func (Optional[T]) MarshalJSON”
func (o Optional[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes a present non-null value.

func (*Optional[T]) UnmarshalJSON

Section titled “func (*Optional[T]) UnmarshalJSON”
func (o *Optional[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a present non-null value without mutating the receiver when decoding fails.

type ParentSchema

Section titled “type ParentSchema”
type ParentSchema struct {
    *ObjectSchema
    Definitions []SchemaProperty
    // The key name for the definitions map.  Defaults to "definitions"
    DefinitionsKeyName string `json:"-"`
    Title              string `json:"title,omitzero"`
}

func (*ParentSchema) AddDefinition

Section titled “func (*ParentSchema) AddDefinition”
func (s *ParentSchema) AddDefinition(key string, value SchemaNode)

func (ParentSchema) MarshalJSON

Section titled “func (ParentSchema) MarshalJSON”
func (s ParentSchema) MarshalJSON() ([]byte, error)

type SchemaFunction

Section titled “type SchemaFunction”
type SchemaFunction func() json.RawMessage

type SchemaMarker

Section titled “type SchemaMarker”
type SchemaMarker struct{}

func NewJSONSchemaBuilder

Section titled “func NewJSONSchemaBuilder”
func NewJSONSchemaBuilder[T any](SchemaFunction) SchemaMarker

NewJSONSchemaBuilder registers a function as being a stub that should be implemented with a proper json schema and, as needed, unmarshaler functionality.

func NewJSONSchemaFunc

Section titled “func NewJSONSchemaFunc”
func NewJSONSchemaFunc[T any](f SchemaMethod[T], _ ...SchemaMethodOption) SchemaMarker

NewJSONSchemaFunc registers a free function that takes the receiver as its sole parameter as a schema entrypoint. It is equivalent to NewJSONSchemaMethod.

func NewJSONSchemaMethod

Section titled “func NewJSONSchemaMethod”
func NewJSONSchemaMethod[T any](SchemaMethod[T], ...SchemaMethodOption) SchemaMarker

NewJSONSchemaMethod registers a struct method as a stub that will be implemented with a proper json schema and, as needed, unmarshaler functionality.

type SchemaMethod

Section titled “type SchemaMethod”
type SchemaMethod[T any] func(T) json.RawMessage

type SchemaMethodOption

Section titled “type SchemaMethodOption”
type SchemaMethodOption interface {
    // contains filtered or unexported methods
}

func AsRef

Section titled “func AsRef”
func AsRef() SchemaMethodOption

AsRef requests that, wherever this type is referenced from another registered schema, it be rendered as a “$ref” into that schema’s “$defs” instead of being inlined.

func WithDiscriminator

Section titled “func WithDiscriminator”
func WithDiscriminator[T any](field T, name string) SchemaMethodOption

func WithEnum

Section titled “func WithEnum”
func WithEnum[T any](field T) SchemaMethodOption

Enum options (v1) - stubs for scanning/type-checking; parsed by scanner

func WithFunction

Section titled “func WithFunction”
func WithFunction[T any](val T, f func(T) json.Marshaler) SchemaMethodOption

func WithInterface

Section titled “func WithInterface”
func WithInterface[T any](field T, options ...InterfaceOption) SchemaMethodOption

Interface options (v1) - stubs for scanning/type-checking; parsed by scanner

func WithInterfaceImpls

Section titled “func WithInterfaceImpls”
func WithInterfaceImpls[T any](field T, impls ...any) SchemaMethodOption

func WithRenderProviders

Section titled “func WithRenderProviders”
func WithRenderProviders() SchemaMethodOption

WithRenderProviders requests generation of RenderedSchema() and provider execution at runtime.

func WithStringerEnum

Section titled “func WithStringerEnum”
func WithStringerEnum[T any](field T) SchemaMethodOption

func WithStructAccessorMethod

Section titled “func WithStructAccessorMethod”
func WithStructAccessorMethod[T, U any](val T, f func(U) json.Marshaler) SchemaMethodOption

func WithStructFunctionMethod

Section titled “func WithStructFunctionMethod”
func WithStructFunctionMethod[T, U any](val U, f func(T, U) json.Marshaler) SchemaMethodOption

type SchemaMethodOptionObj

Section titled “type SchemaMethodOptionObj”
type SchemaMethodOptionObj struct{}

type SchemaNode

Section titled “type SchemaNode”
type SchemaNode = json.Marshaler

func ArraySchema

Section titled “func ArraySchema”
func ArraySchema(items SchemaNode, description string) SchemaNode

func BoolSchema

Section titled “func BoolSchema”
func BoolSchema(description string) SchemaNode

func ConstSchema

Section titled “func ConstSchema”
func ConstSchema[T ~int | ~string](val T, description string) SchemaNode

func EnumSchema

Section titled “func EnumSchema”
func EnumSchema[T ~int | ~string](description string, vals ...T) SchemaNode

func IntSchema

Section titled “func IntSchema”
func IntSchema(description string) SchemaNode

func RefSchemaEl

Section titled “func RefSchemaEl”
func RefSchemaEl(ref string) SchemaNode

A ref into definitions

func StringSchema

Section titled “func StringSchema”
func StringSchema(description string) SchemaNode

func UnionSchemaEl

Section titled “func UnionSchemaEl”
func UnionSchemaEl(alts ...SchemaNode) SchemaNode

An anyOf element

type SchemaProperty

Section titled “type SchemaProperty”
type SchemaProperty struct {
    Key   string
    Value SchemaNode
}

Generated by gomarkdoc