Documentation
¶
Overview ¶
Package schema provides a generic versioned-YAML loader for any file that embeds a schema version field. It handles version probing, unknown-field rejection, 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.
- Strict-decode (KnownFields, single document) into the sealed per-version struct registered for that version.
- Walk the migration chain via Migratable.MigrateToLatest() to produce the current in-memory type T.
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 strict-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") )
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] }
Versioned describes one owned-state-file schema: the YAML key that carries the version, the highest version this build writes, and a factory per supported version that returns a fresh pointer to strict-decode into.
Source Files