schema

Documentation

Overview

Package schema provides the type registry and frontmatter validation.

Index

• Constants
• type Registry
  • func NewRegistry(types map[string]vault.TypeDef) *Registry
  • func NewRegistryWithAliases(types map[string]vault.TypeDef, aliases map[string][]string) *Registry
  • func (r *Registry) Aliases(canonical string) []string
  • func (r *Registry) FieldNamesForLookup(canonical string) []string
  • func (r *Registry) GetTypeDef(typeName string) (vault.TypeDef, bool)
  • func (r *Registry) HasType(typeName string) bool
  • func (r *Registry) IsAlias(canonical, candidate string) bool
  • func (r *Registry) IsFieldAllowed(typeName, field string) bool
  • func (r *Registry) IsFieldPresent(fm map[string]interface{}, canonical string) bool
  • func (r *Registry) ListTypes() []string
  • func (r *Registry) RequiredFields(typeName string) []string
  • func (r *Registry) ValidStatus(typeName, status string) bool

Constants

const CreatedDateFormat = "2006-01-02"

CreatedDateFormat is the canonical format for the `created` field — YYYY-MM-DD date-only UTC. Per manifesto principle 7 (SSOT), every write site for `created` MUST format with this constant:

• internal/template/process.go (init / scaffold default)
• internal/initvault/initvault.go (vault scaffold dates)
• internal/episode/render.go (SessionEnd capture: started_at date)
• internal/mutation/normalize.go (date-field canonicalization)
• internal/fix/fix.go (DefaultCreatedDateResolver: git/mtime/today)

`created` is a humanish "when was this born" stamp. Date-only matches both `git log --format=%as` (author short-date) and the conventional frontmatter date form, so YAML emits unquoted.

Types

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds the type definitions and provides validation methods.

func NewRegistry

func NewRegistry(types map[string]vault.TypeDef) *Registry

NewRegistry creates a Registry from config type definitions with no aliases.

func NewRegistryWithAliases

func NewRegistryWithAliases(types map[string]vault.TypeDef, aliases map[string][]string) *Registry

NewRegistryWithAliases creates a Registry that recognizes per-vault frontmatter field aliases. Aliases let migrating users keep their existing field names (e.g. `last_updated`) while vaultmind validates against canonical names (e.g. `updated`). The map is canonical → list of aliases.

Aliasing is intentionally non-destructive: vaultmind never rewrites frontmatter to normalize field names. The alias and the canonical are equivalent at validation time only.

func (*Registry) Aliases

func (r *Registry) Aliases(canonical string) []string

Aliases returns the registered aliases for a canonical field name, or nil if the canonical name has no aliases.

func (*Registry) FieldNamesForLookup

func (r *Registry) FieldNamesForLookup(canonical string) []string

FieldNamesForLookup returns the canonical name first, followed by any registered aliases. Use this to resolve a field across alternative names when looking it up in stores that key by exact field name (e.g. the frontmatter_kv table) — try names in order, first non-empty wins.

Canonical-first ordering preserves the canonical-precedence contract: when both canonical and alias are present, the canonical value is used.

func (*Registry) GetTypeDef

func (r *Registry) GetTypeDef(typeName string) (vault.TypeDef, bool)

GetTypeDef returns the type definition for a given type name.

func (*Registry) HasType

func (r *Registry) HasType(typeName string) bool

HasType returns whether a type name is registered.

func (*Registry) IsAlias

func (r *Registry) IsAlias(canonical, candidate string) bool

IsAlias reports whether candidate is registered as an alias for canonical. Returns false when candidate equals canonical — a field is not its own alias.

func (*Registry) IsFieldAllowed

func (r *Registry) IsFieldAllowed(typeName, field string) bool

IsFieldAllowed checks if a field name is allowed for a type. Core fields and graph-tier fields are always allowed. Registered aliases for any allowed canonical are also allowed — without this, mutation (`frontmatter set last_updated=...`) would reject the user's existing field name even when the alias was explicitly registered. M1 from the 2026-05-02 review.

func (*Registry) IsFieldPresent

func (r *Registry) IsFieldPresent(fm map[string]interface{}, canonical string) bool

IsFieldPresent reports whether the canonical field OR any of its registered aliases is present in fm with a non-empty value. This is the alias-aware variant of the package-private fmFieldPresent check used by validators — a single point that all required-field checks should call instead of inspecting fm directly.

func (*Registry) ListTypes

func (r *Registry) ListTypes() []string

ListTypes returns all registered type names, sorted alphabetically.

func (*Registry) RequiredFields

func (r *Registry) RequiredFields(typeName string) []string

RequiredFields returns the union of fields that mutation must protect from unset: coreFields (id, type — gating classification) and the type's td.Required (the type's user-supplied contract).

NOT used by validators for the missing-required-field rule — validators iterate td.Required only. Used by mutation/validate.go's unset guard.

func (*Registry) ValidStatus

func (r *Registry) ValidStatus(typeName, status string) bool

ValidStatus checks if a status value is valid for a type. Types with no defined statuses accept any value.