Documentation
¶
Overview ¶
Package schema provides a generic versioned-YAML loader for any file that embeds a schema version field. It handles version probing, field decoding (strict or lenient), single-document enforcement, and in-memory migration to the latest struct shape.
The pattern, extracted once so every versioned file behaves identically:
- Probe the version field (Versioned.VersionKey, default "schemaVersion") from raw YAML before decoding the body.
- Normalise an absent/zero version to 1 (files predating versioning).
- Reject any version greater than the running build supports (a file written by a newer binary) with a human-readable "newer binary" error rather than a surprising decode failure against the current shape.
- Decode (strict or lenient depending on Lenient flag) into the sealed per-version struct registered for that version. Multi-document inputs are always rejected.
- Walk the migration chain via Migratable.MigrateToLatest() to produce the current in-memory type T.
- Run the optional Validate hook on the migrated result.
The genuinely domain-specific parts — the sealed vN structs and their MigrateToLatest field transforms — stay in each consuming package. Only the cross-cutting orchestration lives here.
Index ¶
Constants ¶
const DefaultVersionKey = "schemaVersion"
DefaultVersionKey is the YAML field solo-weaver owned state files use to carry their schema version. It is the default when Versioned.VersionKey is empty; external schemas may override it with any key they prefer.
Variables ¶
var ( // ErrNamespace groups all schema-loading errors. ErrNamespace = errorx.NewNamespace("schema") // ErrMalformed is returned when the document cannot be probed or decoded. ErrMalformed = ErrNamespace.NewType("malformed") // ErrUnsupportedVersion is returned when the document declares a schemaVersion // the running build does not support (typically a file written by a newer binary). ErrUnsupportedVersion = ErrNamespace.NewType("unsupported_version") // ErrValidation is returned when the decoded and migrated document fails // the caller-supplied Validate hook. ErrValidation = ErrNamespace.NewType("validation") )
Functions ¶
This section is empty.
Types ¶
type Migratable ¶
type Migratable[T any] interface { MigrateToLatest() T }
Migratable is a sealed, versioned on-disk struct that knows how to migrate itself up to the latest in-memory shape T. Each owned state file defines one implementation per historical version; the terminal version's MigrateToLatest is the identity-style transform into T, and earlier versions delegate down the chain (vN.migrate().MigrateToLatest()).
type Versioned ¶
type Versioned[T any] struct { // VersionKey is the YAML field carrying the schema version. Empty means // DefaultVersionKey ("schemaVersion"); external schemas may set any key. VersionKey string // CurrentVersion is the highest schema version this build understands and writes. CurrentVersion int // Factories maps a supported version to a constructor returning a fresh // sealed struct (as a Migratable[T]) to decode that version's document into. Factories map[int]func() Migratable[T] // Lenient controls unknown-field handling during decode. When false // (the default), unknown fields cause an error — appropriate for owned // state files written by us. When true, unknown fields are silently // ignored — required by HIP-1494 for externally-authored deployment // packages where additive changes must not break existing consumers. Lenient bool // Validate is an optional hook called after decode and migration. It // receives the migrated T and may return an error to reject the document // on semantic grounds (e.g. missing required fields, invalid enum values). // The error is wrapped as ErrValidation. Nil means no validation. Validate func(T) error }
Versioned describes one versioned-YAML schema: the YAML key that carries the version, the highest version this build writes, a factory per supported version, and optional decode/validation behaviour.
Source Files