Documentation
¶
Overview ¶
Package schema reflects Go values into a version-agnostic JSON Schema representation consumed by the OpenAPI emitters in internal/spec. The three emitters (3.0, 3.1, and 3.2) share the same intermediate Schema type; differences in how nullable, $ref, and other version-specific bits are rendered live in the emitter code, not in this package.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Reflector ¶
type Reflector struct {
// contains filtered or unexported fields
}
Reflector accumulates named component schemas across multiple Reflect calls. A single Reflector must be used for one OpenAPI document build so that component-name collisions between same-named types from different packages are detected and suffixed (User, User_2, ...) consistently with the $ref strings handed out at use sites.
A Reflector is not safe for concurrent use.
The Schema model is version-agnostic (the emitters render Nullable and $ref wrappers per OpenAPI version), so a Reflector needs no version.
func (*Reflector) Components ¶
Components returns the accumulated named component schemas. The map is the Reflector's own; callers must not mutate it while still reflecting.
type Schema ¶
type Schema struct {
// Type is the JSON Schema type: "object", "array", "string", "number",
// "integer", "boolean", or "null". Empty means "no type constraint"
// (matches anything). For interfaces, Type is left empty.
Type string
// Format is the JSON Schema format hint: "int32", "int64", "float",
// "double", "date-time", "date", "time", "byte", "binary", "email", etc.
Format string
// Description is a human-readable description of this value.
Description string
// Properties maps JSON field name to its Schema. Only for Type=="object".
Properties map[string]*Schema
// Required is the list of property names that must be present.
Required []string
// Items is the element schema. Only for Type=="array".
Items *Schema
// AdditionalProperties constrains map values. Only for Type=="object"
// when used as a map type.
AdditionalProperties *Schema
// Ref is a $ref pointer into the components.schemas section. When set,
// the emitter emits a $ref object (wrapped when Nullable, Description,
// or Example are also set) and ignores the structural fields.
Ref string
// Enum, when non-empty, restricts the value to a fixed set.
Enum []any
// Default is the default value, if any.
Default any
// Example is an example value, if any.
Example any
// Nullable is true when the value may be null (Go: a pointer or interface).
// In OpenAPI 3.0 this is emitted as `"nullable": true`. In 3.1/3.2 it is
// expressed by adding "null" to the type array.
Nullable bool
// Extensions is a map of x-stdocs-* and similar extension fields. The
// keys are emitted as-is (e.g. "x-stdocs-type"); values must be
// JSON-serializable.
Extensions map[string]any
}
Schema is a version-agnostic JSON Schema (Draft 2020-12 / OpenAPI 3.1 flavour) value. The OpenAPI emitters serialize the same Schema value into their respective JSON representations. The model is version-agnostic: Nullable is rendered differently in 3.0 ("nullable": true) and 3.1/3.2 (a "type" array including "null") at serialization time, without mutating the model.
func ReflectSchema ¶
ReflectSchema produces a JSON Schema for the given Go value plus the named components it references. It is a convenience wrapper around a single-use Reflector; for whole-document builds use NewReflector so all values share one component namespace.
Source Files