*: allow users to ask for minimal names (#324)

* *: allow users to ask for minimal names

The new --minimal-names flag allows users to ask the generator to come
up with the most minimal name possible, meaning that redundant context
prefixes are omitted and collection type names are inferred from field
names where possible.

A real-world use-case JSON Schema is imported as a test case; some
examples of names before and after:

RolloutSpecificationOrchestratedStepsElem -> OrchestratedStep
RolloutSpecificationOrchestratedStepsElemApplicationsApplyAcrossServiceResources
-> ApplyAcrossServiceResources

Signed-off-by: Steve Kuznetsov <[email protected]>

* chore: tidy up go modules

* fix: resolve issues with new nameScope implementation

* tidy up go modules

---------

Signed-off-by: Steve Kuznetsov <[email protected]>
Co-authored-by: Claudio Beatrice <[email protected]>

Author: stevekuznetsov

go.mod

@@ -14,7 +14,6 @@ require (
 	github.com/sanity-io/litter v1.5.8
 	github.com/spf13/cobra v1.9.1
 	github.com/stretchr/testify v1.10.0
-	golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6
 )
 
 require gopkg.in/yaml.v3 v3.0.1 // indirect

go.sum

@@ -1,5 +1,3 @@
-dario.cat/mergo v1.0.1 h1:Ra4+bf83h2ztPIQYNP99R6m+Y7KfnARDfID+a+vLl4s=
-dario.cat/mergo v1.0.1/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk=
 dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
 dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
@@ -31,7 +29,6 @@ github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An
 github.com/stretchr/testify v0.0.0-20161117074351-18a02ba4a312/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
-golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6/go.mod h1:U6Lno4MTRCDY+Ba7aCcauB9T60gsv5s4ralQzP72ZoQ=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

go.work.sum

@@ -1,10 +1,13 @@
+dario.cat/mergo v1.0.0/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk=
 github.com/atombender/go-jsonschema/tests/data v0.0.0-20231003003002-2b73c089a581/go.mod h1:kLoRQLRVy+GT9/PG2e3u31DPvDmtFEn7pX6FItvbqlA=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/fatih/color v1.10.0/go.mod h1:ELkj/draVOlAH/xkhN6mQ50Qd0MPOk5AAr3maGEBuJM=
 github.com/fatih/color v1.17.0/go.mod h1:YZ7TlrGPkiz6ku9fK3TLD/pl3CpsiFyu8N92HLgmosI=
 github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
 github.com/go-playground/assert/v2 v2.0.1/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/goccy/go-yaml v1.15.23/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/mattn/go-colorable v0.1.8/go.mod h1:u6P/XSegPjTcexA+o6vUJrdnUu04hMope9wVRipJSqc=
 github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
 github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
@@ -32,13 +35,15 @@ golang.org/x/net v0.30.0/go.mod h1:2wGyMJ5iFasEhkwi13ChkO/t1ECNC4X4eBKkVFyYFlU=
 golang.org/x/net v0.32.0/go.mod h1:CwU0IoeOlnQQWJ6ioyFrfRuomB8GKF6KbYXZVyeXNfs=
 golang.org/x/net v0.37.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
 golang.org/x/net v0.39.0/go.mod h1:X7NRbYVEA+ewNkCNyJ513WmMdQ3BineSwVtN2zD/d+E=
+golang.org/x/net v0.40.0/go.mod h1:y0hY0exeL2Pku80/zKK7tpntoX23cqL3Oa6njdgRtds=
 golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.8.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.9.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sync v0.13.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -49,9 +54,11 @@ golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.23.0 h1:YfKFowiIMvtgl1UERQoTPPToxltDeZfbj4H7dVUCwmM=
 golang.org/x/sys v0.23.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.25.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/telemetry v0.0.0-20240521205824-bda55230c457/go.mod h1:pRgIJT+bRLFKnoM1ldnzKoxTIn14Yxz928LQRYYgIN0=
 golang.org/x/term v0.6.0/go.mod h1:m6U89DPEgQRMq3DNkDClhWw02AUbt2daBVO4cn4Hv9U=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
@@ -70,5 +77,7 @@ golang.org/x/tools v0.27.0/go.mod h1:sUi0ZgbwW9ZPAq26Ekut+weQPR5eIM6GQLQ1Yjm1H0Q
 golang.org/x/tools v0.28.0/go.mod h1:dcIOrVd3mfQKTgrDVQHqCPMWy6lnhfhtX3hLXYVLfRw=
 golang.org/x/tools v0.31.0/go.mod h1:naFTU+Cev749tSJRXJlna0T3WxKvb1kWEx15xA4SdmQ=
 golang.org/x/tools v0.32.0/go.mod h1:ZxrU41P/wAbZD8EDa6dDCa6XfpkhJ7HFMjHJXfBDu8s=
+golang.org/x/tools v0.33.0/go.mod h1:CIJMaWEY88juyUfo7UbgPqbC8rU2OqfAV1h2Qp0oMYI=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da/go.mod h1:NDW/Ps6MPRej6fsCIbMTohpP40sJ/P/vI1MoTEGwX90=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=

main.go

@@ -32,6 +32,7 @@ var (
 	tags                      []string
 	structNameFromTitle       bool
 	minSizedInts              bool
+	minimalNames              bool
 	disableReadOnlyValidation bool
 
 	errFlagFormat = errors.New("flag must be in the format URI=PACKAGE")
@@ -78,6 +79,7 @@ var (
 				Tags:                      tags,
 				OnlyModels:                onlyModels,
 				MinSizedInts:              minSizedInts,
+				MinimalNames:              minimalNames,
 				DisableReadOnlyValidation: disableReadOnlyValidation,
 			}
 			for _, id := range allKeys(schemaPackageMap, schemaOutputMap, schemaRootTypeMap) {
@@ -181,6 +183,8 @@ also look for foo.json if --resolve-extension json is provided.`)
 		"Uses sized int and uint values based on the min and max values for the field")
 	rootCmd.PersistentFlags().BoolVar(&disableReadOnlyValidation, "disable-readonly-validation", false,
 		"Do not include validation of readonly fields")
+	rootCmd.PersistentFlags().BoolVar(&minimalNames, "minimal-names", false,
+		"Uses the shortest possible names")
 
 	abortWithErr(rootCmd.Execute())
 }

pkg/generator/config.go

@@ -3,19 +3,33 @@ package generator
 import "github.com/atombender/go-jsonschema/pkg/schemas"
 
 type Config struct {
-	SchemaMappings      []SchemaMapping
-	ExtraImports        bool
-	Capitalizations     []string
-	ResolveExtensions   []string
-	YAMLExtensions      []string
-	DefaultPackageName  string
-	DefaultOutputName   string
+	SchemaMappings []SchemaMapping
+	// ExtraImports allows the generator to pull imports from outside the standard library.
+	ExtraImports bool
+	// Capitalizations configures capitalized forms for identifiers which take precedence over the default algorithm.
+	Capitalizations []string
+	// ResolveExtensions configures file extensions to use when resolving schema names.
+	ResolveExtensions []string
+	// YAMLExtensions configures the file extensions that are recognized as YAML files.
+	YAMLExtensions []string
+	// DefaultPackageName configures the package to declare files under.
+	DefaultPackageName string
+	// DefaultOutputName configures the file to write.
+	DefaultOutputName string
+	// StructNameFromTitle configures the generator to use the schema title as the generated struct name.
 	StructNameFromTitle bool
-	Warner              func(string)
-	Tags                []string
-	OnlyModels          bool
-	MinSizedInts        bool
-	Loader              schemas.Loader
+	// Warner provides a handler for warning messages.
+	Warner func(string)
+	// Tags specifies which struct tags should be generated.
+	Tags []string
+	// OnlyModels configures the generator to omit unmarshal methods, validations, anything but models.
+	OnlyModels bool
+	// MinSizedInts configures the generator to use the smallest int and uint types based on schema maximum values.
+	MinSizedInts bool
+	// MinimalNames configures the generator to use the shortest identifier names possible.
+	MinimalNames bool
+	// Loader provides a schema loader for the generator.
+	Loader schemas.Loader
 	// When DisableOmitempty is set to true,
 	// an "omitempty" tag will never be present in generated struct fields.
 	// When DisableOmitempty is set to false,

pkg/generator/generate.go

@@ -34,13 +34,14 @@ var (
 )
 
 type Generator struct {
-	caser      *text.Caser
-	config     Config
-	inScope    map[qualifiedDefinition]struct{}
-	outputs    map[string]*output
-	warner     func(string)
-	formatters []formatter
-	loader     schemas.Loader
+	caser        *text.Caser
+	config       Config
+	inScope      map[qualifiedDefinition]struct{}
+	outputs      map[string]*output
+	warner       func(string)
+	formatters   []formatter
+	loader       schemas.Loader
+	minimalNames bool
 }
 
 type qualifiedDefinition struct {
@@ -59,13 +60,14 @@ func New(config Config) (*Generator, error) {
 	}
 
 	generator := &Generator{
-		caser:      text.NewCaser(config.Capitalizations, config.ResolveExtensions),
-		config:     config,
-		inScope:    map[qualifiedDefinition]struct{}{},
-		outputs:    map[string]*output{},
-		warner:     config.Warner,
-		formatters: formatters,
-		loader:     config.Loader,
+		caser:        text.NewCaser(config.Capitalizations, config.ResolveExtensions),
+		config:       config,
+		inScope:      map[qualifiedDefinition]struct{}{},
+		outputs:      map[string]*output{},
+		warner:       config.Warner,
+		formatters:   formatters,
+		loader:       config.Loader,
+		minimalNames: config.MinimalNames,
 	}
 
 	if config.Loader == nil {
@@ -202,7 +204,8 @@ func (g *Generator) beginOutput(
 	}
 
 	output := &output{
-		warner: g.warner,
+		minimalNames: g.minimalNames,
+		warner:       g.warner,
 		file: &codegen.File{
 			FileName: outputName,
 			Package:  pkg,

pkg/generator/name_scope.go

@@ -16,6 +16,14 @@ func (ns nameScope) string() string {
 	return strings.Join(ns.stack, "")
 }
 
+func (ns nameScope) stringFrom(start int) string {
+	if start >= len(ns.stack) {
+		return ""
+	}
+
+	return strings.Join(ns.stack[start:], "")
+}
+
 func (ns nameScope) add(s string) nameScope {
 	result := make([]string, len(ns.stack)+1)
 	copy(result, ns.stack)
@@ -25,3 +33,15 @@ func (ns nameScope) add(s string) nameScope {
 
 	return ns
 }
+
+func (ns nameScope) last() (string, bool) {
+	if len(ns.stack) == 0 {
+		return "", false
+	}
+
+	return ns.stack[len(ns.stack)-1], true
+}
+
+func (ns nameScope) len() int {
+	return len(ns.stack)
+}

pkg/generator/output.go

@@ -11,6 +11,7 @@ import (
 )
 
 type output struct {
+	minimalNames  bool
 	file          *codegen.File
 	declsByName   map[string]*codegen.TypeDecl
 	declsBySchema map[*schemas.Type]*codegen.TypeDecl
@@ -49,15 +50,32 @@ func (o *output) isUniqueTypeName(name string) bool {
 	return !ok || (ok && v.Type == nil)
 }
 
-func (o *output) uniqueTypeName(name string) string {
-	v, ok := o.declsByName[name]
+// uniqueTypeName finds the shortest identifier in a name scope that yields a unique type name.
+// If a given suffix on the name scope is not unique, more context from the scope is added. If the
+// entire context does not yield a unique name, a numeric suffix is used.
+// TODO: we should check for schema equality on name collisions here to deduplicate identifiers.
+func (o *output) uniqueTypeName(scope nameScope) string {
+	if o.minimalNames {
+		for i := scope.len() - 1; i >= 0; i-- {
+			name := scope.stringFrom(i)
+
+			v, ok := o.declsByName[name]
+			if !ok || (ok && v.Type == nil) {
+				// An identifier using the current amount of name context is unique, use it.
+				return name
+			}
+		}
+	}
+
+	// If we can't make a unique name with the entire context, attempt a numeric suffix.
+	count := 1
+	name := scope.string()
 
+	v, ok := o.declsByName[name]
 	if !ok || (ok && v.Type == nil) {
 		return name
 	}
 
-	count := 1
-
 	for {
 		suffixed := fmt.Sprintf("%s_%d", name, count)
 		if _, ok := o.declsByName[suffixed]; !ok {

pkg/generator/schema_generator.go

@@ -276,7 +276,7 @@ func (g *schemaGenerator) generateDeclaredType(t *schemas.Type, scope nameScope)
 	}
 
 	decl := codegen.TypeDecl{
-		Name:       g.output.uniqueTypeName(scope.string()),
+		Name:       g.output.uniqueTypeName(scope),
 		Comment:    t.Description,
 		SchemaType: t,
 	}
@@ -523,7 +523,7 @@ func (g *schemaGenerator) generateType(t *schemas.Type, scope nameScope) (codege
 			return nil, errArrayPropertyItems
 		}
 
-		elemType, err := g.generateType(t.Items, scope.add("Elem"))
+		elemType, err := g.generateType(t.Items, g.singularScope(scope))
 		if err != nil {
 			return nil, err
 		}
@@ -1004,7 +1004,7 @@ func (g *schemaGenerator) generateTypeInline(t *schemas.Type, scope nameScope) (
 			} else {
 				var err error
 
-				theType, err = g.generateTypeInline(t.Items, scope.add("Elem"))
+				theType, err = g.generateTypeInline(t.Items, g.singularScope(scope))
 				if err != nil {
 					return nil, err
 				}
@@ -1026,7 +1026,21 @@ func (g *schemaGenerator) generateTypeInline(t *schemas.Type, scope nameScope) (
 	return dt, nil
 }
 
-func (g *schemaGenerator) generateEnumType(t *schemas.Type, scope nameScope) (codegen.Type, error) {
+// singularScope attempts to create a name scope for an element of a collection. If the parent collection
+// has a plural name like "Actions", then the singular name for the element will be "Action". If the collection
+// is not plural, like "WhateverElse", then the element's name will be "WhateverElseElem".
+func (g *Generator) singularScope(scope nameScope) nameScope {
+	last, ok := scope.last()
+	if g.minimalNames && ok && strings.HasSuffix(last, "s") {
+		return scope.add(strings.TrimSuffix(last, "s"))
+	}
+
+	return scope.add("Elem")
+}
+
+func (g *schemaGenerator) generateEnumType(
+	t *schemas.Type, scope nameScope,
+) (codegen.Type, error) {
 	if len(t.Enum) == 0 {
 		return nil, errEnumArrCannotBeEmpty
 	}
@@ -1123,7 +1137,7 @@ func (g *schemaGenerator) generateEnumType(t *schemas.Type, scope nameScope) (co
 	}
 
 	enumDecl := codegen.TypeDecl{
-		Name:       g.output.uniqueTypeName(scope.string()),
+		Name:       g.output.uniqueTypeName(scope),
 		Type:       enumType,
 		SchemaType: t,
 	}

tests/data/deeplyNested/Makefile

@@ -0,0 +1,2 @@
+standalone/RolloutSpecification.json:
+	wget --output-document=$@ --quiet https://ev2schema.azure.net/schemas/2020-01-01/$(notdir $@)