Documentation
¶
Overview ¶
Package jsonschema provides helpers to generate JSON Schema documents from Go types. It supports building a root schema and collecting reusable component schemas for nested types.
Index ¶
- Constants
- func GenerateSchema(t reflect.Type) map[string]any
- func GenerateSchemaRawMessage(t reflect.Type) json.RawMessage
- func GenerateSchemaWithComponents(t reflect.Type) (map[string]any, map[string]any)
- func RegisterSchema(t reflect.Type, schema map[string]any)
- func SchemaFrom[T any]() json.RawMessage
- type Builder
- type OrderedMap
Constants ¶
const ( // Schema keywords TypeKey = "type" PropertiesKey = "properties" RequiredKey = "required" ItemsKey = "items" AdditionalPropertiesKey = "additionalProperties" RefKey = "$ref" MinimumKey = "minimum" MaximumKey = "maximum" MultipleOfKey = "multipleOf" MinLengthKey = "minLength" MaxLengthKey = "maxLength" PatternKey = "pattern" FormatKey = "format" MinItemsKey = "minItems" MaxItemsKey = "maxItems" UniqueItemsKey = "uniqueItems" EnumKey = "enum" TitleKey = "title" DescriptionKey = "description" DefaultKey = "default" ConstKey = "const" ExamplesKey = "examples" MinPropertiesKey = "minProperties" MaxPropertiesKey = "maxProperties" ExclusiveMinimumKey = "exclusiveMinimum" ExclusiveMaximumKey = "exclusiveMaximum" PatternPropertiesKey = "patternProperties" ContainsKey = "contains" IfKey = "if" ThenKey = "then" ElseKey = "else" DefsKey = "$defs" SchemaKey = "$schema" IDKey = "$id" OneOfKey = "oneOf" AnyOfKey = "anyOf" AllOfKey = "allOf" NotKey = "not" JSONTag = "json" // Schema types TypeArray = "array" TypeObject = "object" TypeInteger = "integer" TypeNumber = "number" TypeBoolean = "boolean" TypeString = "string" )
JSON Schema constants for keys and types.
Variables ¶
This section is empty.
Functions ¶
func GenerateSchemaRawMessage ¶
func GenerateSchemaRawMessage(t reflect.Type) json.RawMessage
GenerateSchemaRawMessage returns a JSON Schema as a raw JSON message. It returns nil if the schema cannot be marshaled.
func GenerateSchemaWithComponents ¶
GenerateSchema returns the JSON Schema for the provided reflect.Type. This is a convenience wrapper around Builder.Schema.
func RegisterSchema ¶
RegisterSchema registers a custom JSON Schema for a Go type.
func SchemaFrom ¶
func SchemaFrom[T any]() json.RawMessage
SchemaFrom generates a JSON Schema for a generic type T.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder builds JSON Schema documents for Go types and optionally collects reusable component schemas.
Use a Builder when you need to generate a schema and also obtain the component definitions (for example, when producing OpenAPI-like components/schemas). Builders are lightweight and intended to be created per generation. A Builder is not safe for concurrent use: do not call methods on the same Builder instance from multiple goroutines simultaneously.
func NewBuilder ¶
func NewBuilder() *Builder
NewBuilder returns a new Builder with an initialized components map.
Example:
b := jsonschema.NewBuilder()
root := b.Schema(reflect.TypeOf(MyType{}))
The returned Builder can be reused for additional generations, but its internal components map will only be populated when calling SchemaWithComponents.
func (*Builder) Components ¶
Components returns the map of collected component schemas. The map keys are component names and the values are JSON Schema objects (map[string]any). The map is populated when calling SchemaWithComponents. The returned map is the Builder's internal storage and may be mutated by callers; if you need an immutable snapshot, copy the map before using it concurrently.
func (*Builder) Schema ¶
Schema generates a JSON Schema for the provided type and returns the schema as a generic map[string]any. This method does not populate the Builder's components map — use SchemaWithComponents when you also need nested component definitions.
Note: Schema expects a non-nil reflect.Type. Passing a nil reflect.Type will cause a panic in the current implementation.
func (*Builder) SchemaWithComponents ¶
SchemaWithComponents generates a JSON Schema for the provided type and also returns a map of component schemas discovered during generation. The first return value is the root schema, the second is the components map suitable for placing under `#/components/schemas` in OpenAPI-style outputs.
The components map is owned by the Builder and may be mutated by subsequent calls to SchemaWithComponents on the same Builder. If you need to preserve components between calls, copy the map.
Note: Passing a nil reflect.Type will panic.
type OrderedMap ¶
type OrderedMap struct {
// contains filtered or unexported fields
}
OrderedMap is a simple map that preserves insertion order of keys. It provides JSON and YAML marshaling that respects the insertion order, which is useful for predictable output in tests and APIs.
func (*OrderedMap) MarshalJSON ¶
func (m *OrderedMap) MarshalJSON() ([]byte, error)
MarshalJSON marshals the OrderedMap to JSON using the insertion order.
func (*OrderedMap) MarshalYAML ¶
func (m *OrderedMap) MarshalYAML() (any, error)
MarshalYAML marshals the OrderedMap to a YAML node preserving order.
func (*OrderedMap) Set ¶
func (m *OrderedMap) Set(key string, value any)
Set inserts or updates a key while preserving insertion order for new keys.
func (*OrderedMap) ToMap ¶
func (m *OrderedMap) ToMap() map[string]any
ToMap returns the underlying map storage. Note: the returned map is the internal storage and mutating it will affect the OrderedMap.
Source Files