Exhaustive, no-compat playbook for migrating Glazed code from the legacy layers/parameters API to the schema/fields/values/sources API.
This is a breaking migration. The legacy packages (layers, parameters, middlewares, parsed layers) and their alias shims have been removed. You must update imports, type names, and call sites to the new API (schema, fields, values, sources).
This playbook is intentionally exhaustive. It is designed to be a systematic, error-resistant checklist that you can follow in large codebases.
go test ./... and fix remaining errors.Old -> New
github.com/go-go-golems/glazed/pkg/cmds/layers -> github.com/go-go-golems/glazed/pkg/cmds/schemagithub.com/go-go-golems/glazed/pkg/cmds/parameters -> github.com/go-go-golems/glazed/pkg/cmds/fieldsgithub.com/go-go-golems/glazed/pkg/cmds/middlewares -> github.com/go-go-golems/glazed/pkg/cmds/sourcesgithub.com/go-go-golems/glazed/pkg/cmds/parsedlayers (or layers parsed types) -> github.com/go-go-golems/glazed/pkg/cmds/valuesOld:
cmds.CommandDefinition, cmds.NewCommandDefinitioncmds.CommandDefinitionOptioncmds.CommandDescription.Layers / WithLayers...New:
cmds.CommandDescription, cmds.NewCommandDescriptioncmds.CommandDescriptionOptionCommandDescription.Schema and WithSchema, WithSections, WithSectionsMap, SetSectionsExample:
// Old
cmd := cmds.NewCommandDefinition("demo",
cmds.WithShort("Demo"),
cmds.WithLayersList(demoLayer),
)
// New
cmd := cmds.NewCommandDescription("demo",
cmds.WithShort("Demo"),
cmds.WithSections(demoSection),
)
Old (layers):
layers.ParameterLayer -> schema.Sectionlayers.ParameterLayerImpl -> schema.SectionImpllayers.ParameterLayers -> schema.Schemalayers.NewParameterLayer -> schema.NewSectionlayers.NewParameterLayers -> schema.NewSchemaAddLayerToCobraCommand -> AddSectionToCobraCommandNew (schema):
section, _ := schema.NewSection("demo", "Demo",
schema.WithPrefix("demo-"),
schema.WithFields(
fields.New("api-key", fields.TypeString),
),
)
schema_ := schema.NewSchema(schema.WithSections(section))
Section interface highlights:
AddFields(...*fields.Definition)GetDefinitions() *fields.DefinitionsInitializeDefaultsFromStruct(s any)InitializeDefaultsFromFields(map[string]any)InitializeStructFromFieldDefaults(s any)AddSectionToCobraCommand(cmd *cobra.Command)Old (parameters):
ParameterDefinition -> fields.DefinitionParameterDefinitions -> fields.DefinitionsParameterType -> fields.TypeParsedParameter -> fields.FieldValueParsedParameters -> fields.FieldValuesparameters.NewParameterDefinition -> fields.NewNew (fields):
field := fields.New("limit", fields.TypeInteger, fields.WithDefault(10))
Old:
layers.ParsedLayer -> values.SectionValueslayers.ParsedLayers -> values.ValuesparsedLayers.InitializeStruct(...) -> values.Values.DecodeSectionInto(...)New:
vals := values.New()
// ... populate with sources
settings := &MySettings{}
if err := vals.DecodeSectionInto(schema.DefaultSlug, settings); err != nil {
return err
}
Old (middlewares):
middlewares.ParseFromCobraCommand -> sources.FromCobramiddlewares.GatherArguments -> sources.FromArgsmiddlewares.UpdateFromEnv -> sources.FromEnvmiddlewares.SetFromDefaults -> sources.FromDefaultsmiddlewares.LoadParametersFromFile(s) -> sources.FromFile / sources.FromFilesmiddlewares.UpdateFromMap -> sources.FromMap / sources.FromMapFirstmiddlewares.ExecuteMiddlewares -> sources.Executefields.WithParseStepSource -> sources.WithSourcemiddlewares.WrapWithWhitelistedLayers -> sources.WrapWithWhitelistedSectionsmiddlewares.WrapWithWhitelistedLayerParameters -> sources.WrapWithWhitelistedSectionFieldsmiddlewares.BlacklistLayers -> sources.BlacklistSectionsmiddlewares.BlacklistLayerParameters -> sources.BlacklistSectionFieldsmiddlewares.UpdateFromMapAsDefaultFirst -> sources.FromMapAsDefaultFirstNew:
vals := values.New()
err := sources.Execute(schema_, vals,
sources.FromCobra(cmd, sources.WithSource("flags")),
sources.FromEnv("MYAPP", sources.WithSource("env")),
sources.FromFile("config.yaml", sources.WithParseOptions(sources.WithSource("config"))),
sources.FromDefaults(sources.WithSource(sources.SourceDefaults)),
)
Signature change to keep in mind:
// Old
middlewares.ExecuteMiddlewares(description.Layers, parsedLayers, middlewares_...)
// New
sources.Execute(description.Schema.Clone(), parsedValues, middlewares_...)
If you load commands from YAML, replace layers: with sections:. The legacy layers: key no longer matches the new schema API.
# Old
layers:
- slug: default
name: Default
flags:
- name: limit
type: int
# New
sections:
- slug: default
name: Default
flags:
- name: limit
type: int
Old:
settings.NewGlazedLayer -> settings.NewGlazedSectionlogging.LoggingLayer -> logging.LoggingSectionAddLoggingLayerToRootCommand -> AddLoggingSectionToRootCommandNew:
glazedSection, _ := settings.NewGlazedSection()
loggingSection, _ := logging.NewLoggingSection("myapp")
Old:
TargetLayer -> TargetSectionTargetParameter -> TargetFieldWithValuesForLayers -> WithValuesForSectionsUpdate any config mapping or pattern rules to refer to sections/fields explicitly.
Only glazed:"..." is supported. Remove legacy aliases if present (for example, glazed.parameter:"...").
Example:
// Old
type Settings struct {
Host string `glazed.parameter:"host"`
}
// New
type Settings struct {
Host string `glazed:"host"`
}
If you define fields via YAML, the short flag key is now shortFlag (not shorthand).
Example:
flags:
- name: host
type: string
help: Database host
shortFlag: H
If you reference example paths or files in docs/scripts:
cmd/examples/parameter-types -> cmd/examples/field-typesmisc/json-parameters-from-json.json -> misc/json-fields-from-json.jsonrg -n -i "layer|parameter" . (exclude ttmp/ if you keep historical notes)gofmt -w <changed files>go test ./...| Error | Cause | Fix |
|---|---|---|
undefined: cmds.NewCommandDefinition | Alias removed | Use cmds.NewCommandDescription |
undefined: layers.ParameterLayer | Old package removed | Use schema.Section |
parsedLayers.InitializeStruct missing | Method removed | Use Values.DecodeSectionInto |
middlewares.ExecuteMiddlewares missing | Package removed | Use sources.Execute |
undefined: cli.BuildCobraCommandFromBareCommand | Helper removed | Use cli.BuildCobraCommand |
undefined: logging.AddLoggingLayerToRootCommand | Renamed | Use logging.AddLoggingSectionToRootCommand |
R<score> <old> <new>rg -n -i "layer|parameter" glazed -g '!**/ttmp/**'go test ./...golangci-lint run -v --max-same-issues=100gosec -exclude=G101,G304,G301,G306,G204 -exclude-dir=ttmp -exclude-dir=.history ./...govulncheck ./...