Documentation
¶
Overview ¶
Package schema is Harbor's neutral Go-type -> JSON-Schema derivation home. It converts a reflect.Type into a JSON Schema document (structs, slices, maps, pointers, primitives, time.Time, json.RawMessage) and wraps the shared jsonschema/v6 compiler so callers can compile a derived (or hand-authored) schema document into a reusable validator.
This package was promoted out of the in-process tool driver (internal/tools/drivers/inproc) so the derivation has exactly ONE implementation with TWO consumers: RegisterFunc (deriving a registered function's ArgsSchema/OutSchema) and the typed embed binding (internal/runtime/assemble.RunTyped, deriving a run's output schema from its generic type parameter). Promoting it here also closes a pre-existing §13 seam violation: the flow engine (internal/runtime/flow) needed the SAME derivation but could only reach it by importing a concrete tool driver package, which §4.4/§13 forbid outside the driver's sanctioned importers. This package has no tool-catalog concept at all, so any caller can depend on it without gaining a forbidden concrete-driver import.
Dependency direction (binding): this package MUST NOT import any concrete tool driver (internal/tools/drivers/...). The dependency points driver -> schema, never schema -> driver.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrSchemaBuild = errors.New("schema: failed to build JSON schema")
ErrSchemaBuild is returned when the schema compiler chokes on a derived (or caller-supplied) JSON-Schema document. A derivation-time failure here indicates a deriver bug; callers should report it.
var ErrUnsupportedType = errors.New("schema: unsupported type for derivation")
ErrUnsupportedType is returned when the derivation encounters a Go shape it cannot represent as JSON Schema (non-empty interfaces, channels, function-typed fields, cyclic structures, non-string map keys). The error message names the offending Go field so the caller can fix it.
Functions ¶
func Compile ¶
func Compile(schemaBytes []byte) (*jsonschema.Schema, error)
Compile compiles a JSON-Schema document into a reusable validator. Wraps the schema in a synthetic URL so the compiler resolves it stand-alone.
func Validate ¶
func Validate(schema *jsonschema.Schema, instance json.RawMessage) error
Validate decodes instance into a JSON value and validates it against schema. The error is human-readable (it carries the failing instance path + the constraint that failed). A nil schema passes (no constraint configured). An empty instance is treated as JSON null so a schema requiring an object fails loud rather than passing vacuously.
Types ¶
type Map ¶
Map is a typed alias for the map[string]any shape JSON-Schema documents use. Exported for readability at call sites that build or inspect a derived document directly.
func Derive ¶
Derive converts a Go type into a JSON Schema object. Returns ErrUnsupportedType for shapes the deriver can't represent (interfaces, channels, function values, cyclic recursion).
Coverage:
- bool -> {"type": "boolean"}
- int / int8...64 / uint / uint8...64 -> {"type": "integer"}
- float32 / float64 -> {"type": "number"}
- string -> {"type": "string"}
- []byte -> {"type": "string", "contentEncoding": "base64"}
- []T -> {"type": "array", "items": Schema(T)}
- map[string]T -> {"type": "object", "additionalProperties": Schema(T)}
- struct -> {"type": "object", "properties": {...}, "required": [...]}
- *T -> Schema(T) with the property dropped from "required" at the parent level
- time.Time -> {"type": "string", "format": "date-time"}
- json.RawMessage -> {} (any-shaped; no constraint)
Struct fields use the `json:"name"` tag for property names; an `,omitempty` modifier removes the field from `required`. A `-` json tag skips the field entirely.
Source Files