Fix schema filtering, external ApplyDefaults, and primitive component aliases

Fixes: #3

1. Schema filtering by tags/operation IDs: GatherSchemas now accepts
   OutputOptions and skips operations excluded by tag or operation ID
   filters. A new prune-unreferenced-schemas option removes component
   schemas that are not ref'd by any gathered schema.

2. ApplyDefaults on external types: External ref fields now use
   reflection (reflect.ValueOf().MethodByName) instead of direct method
   calls, since we cannot know at codegen time whether the external type
   implements ApplyDefaults.

3. Primitive component schema aliases: Component schemas always generate
   Go type aliases (e.g., type Name = string), even for primitive types.
   This ensures external packages can reference them by name.

Also adds doc.go with go:generate directives to external_ref test
packages and extends the test specs with cross-package reference
scenarios (Employee composed of external Name/Address/Occupation fields).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mromaszewicz

experimental/internal/codegen/clientgen_test.go

@@ -20,7 +20,7 @@ func TestClientGenerator(t *testing.T) {
 
 	// Gather schemas to build schema index
 	contentTypeMatcher := NewContentTypeMatcher(DefaultContentTypes())
-	schemas, err := GatherSchemas(doc, contentTypeMatcher)
+	schemas, err := GatherSchemas(doc, contentTypeMatcher, OutputOptions{})
 	require.NoError(t, err, "Failed to gather schemas")
 
 	// Compute names for schemas
@@ -90,7 +90,7 @@ func TestClientGenerator_FormEncoded(t *testing.T) {
 	require.NoError(t, err, "Failed to parse comprehensive spec")
 
 	contentTypeMatcher := NewContentTypeMatcher(DefaultContentTypes())
-	schemas, err := GatherSchemas(doc, contentTypeMatcher)
+	schemas, err := GatherSchemas(doc, contentTypeMatcher, OutputOptions{})
 	require.NoError(t, err, "Failed to gather schemas")
 
 	converter := NewNameConverter(NameMangling{}, NameSubstitutions{})

experimental/internal/codegen/codegen.go

@@ -26,15 +26,22 @@ func Generate(doc libopenapi.Document, specData []byte, cfg Configuration) (stri
 	// Create content type short namer for friendly type names
 	contentTypeNamer := NewContentTypeShortNamer(cfg.ContentTypeShortNames)
 
-	// Pass 1: Gather all schemas that need types
-	schemas, err := GatherSchemas(doc, contentTypeMatcher)
+	// Pass 1: Gather all schemas that need types.
+	// Operation filters (include/exclude tags, operation IDs) are applied during
+	// gathering so that schemas from excluded operations are never collected.
+	schemas, err := GatherSchemas(doc, contentTypeMatcher, cfg.OutputOptions)
 	if err != nil {
 		return "", fmt.Errorf("gathering schemas: %w", err)
 	}
 
-	// Filter excluded schemas
+	// Filter explicitly excluded schemas
 	schemas = FilterSchemasByName(schemas, cfg.OutputOptions.ExcludeSchemas)
 
+	// Optionally prune component schemas that aren't referenced by any other schema
+	if cfg.OutputOptions.PruneUnreferencedSchemas {
+		schemas = PruneUnreferencedSchemas(schemas)
+	}
+
 	// Pass 2: Compute names for all schemas
 	converter := NewNameConverter(cfg.NameMangling, cfg.NameSubstitutions)
 	ComputeSchemaNames(schemas, converter, contentTypeNamer)
@@ -492,8 +499,11 @@ func generateStructType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 		code := structCode + "\n" + marshalCode + "\n" + unmarshalCode
 
 		// Generate ApplyDefaults method if needed
-		if applyDefaults := GenerateApplyDefaults(desc.ShortName, fields); applyDefaults != "" {
+		if applyDefaults, needsReflect := GenerateApplyDefaults(desc.ShortName, fields); applyDefaults != "" {
 			code += "\n" + applyDefaults
+			if needsReflect {
+				gen.AddImport("reflect")
+			}
 		}
 
 		return code
@@ -502,8 +512,11 @@ func generateStructType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 	code := GenerateStruct(desc.ShortName, fields, doc, gen.TagGenerator())
 
 	// Generate ApplyDefaults method if needed
-	if applyDefaults := GenerateApplyDefaults(desc.ShortName, fields); applyDefaults != "" {
+	if applyDefaults, needsReflect := GenerateApplyDefaults(desc.ShortName, fields); applyDefaults != "" {
 		code += "\n" + applyDefaults
+		if needsReflect {
+			gen.AddImport("reflect")
+		}
 	}
 
 	return code
@@ -716,8 +729,11 @@ func generateAllOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 	}
 
 	// Generate ApplyDefaults method if needed
-	if applyDefaults := GenerateApplyDefaults(desc.ShortName, finalFields); applyDefaults != "" {
+	if applyDefaults, needsReflect := GenerateApplyDefaults(desc.ShortName, finalFields); applyDefaults != "" {
 		code += "\n" + applyDefaults
+		if needsReflect {
+			gen.AddImport("reflect")
+		}
 	}
 
 	return code

experimental/internal/codegen/configuration.go

@@ -52,6 +52,10 @@ type OutputOptions struct {
 	ExcludeOperationIDs []string `yaml:"exclude-operation-ids,omitempty"`
 	// ExcludeSchemas excludes schemas with the given names from generation. Ignored when empty.
 	ExcludeSchemas []string `yaml:"exclude-schemas,omitempty"`
+	// PruneUnreferencedSchemas removes component schemas that are not $ref'd by any other
+	// gathered schema. When combined with tag/operation filtering, this effectively removes
+	// schemas that are only used by excluded operations.
+	PruneUnreferencedSchemas bool `yaml:"prune-unreferenced-schemas,omitempty"`
 }
 
 // ModelsPackage specifies an external package containing the model types.

experimental/internal/codegen/filter.go

@@ -63,6 +63,66 @@ func FilterSchemasByName(schemas []*SchemaDescriptor, excludeNames []string) []*
 	return result
 }
 
+// PruneUnreferencedSchemas removes component schemas that are not $ref'd by any
+// other gathered schema. This walks the entire schema descriptor tree, collects
+// all $ref paths, and removes component schemas whose path doesn't appear in
+// that set. Non-component schemas (inline path schemas, etc.) are always kept.
+func PruneUnreferencedSchemas(schemas []*SchemaDescriptor) []*SchemaDescriptor {
+	// Collect all $ref paths from all schemas
+	referenced := make(map[string]bool)
+	for _, s := range schemas {
+		collectRefsFromDescriptor(s, referenced)
+	}
+
+	result := make([]*SchemaDescriptor, 0, len(schemas))
+	for _, s := range schemas {
+		// Always keep non-component schemas (inline path schemas, etc.)
+		if !s.IsComponentSchema() {
+			result = append(result, s)
+			continue
+		}
+
+		// Keep component schemas that are referenced by something
+		if referenced[s.Path.String()] {
+			result = append(result, s)
+		}
+	}
+	return result
+}
+
+// collectRefsFromDescriptor walks a schema descriptor tree and adds all
+// internal $ref paths to the referenced set.
+func collectRefsFromDescriptor(desc *SchemaDescriptor, referenced map[string]bool) {
+	if desc == nil {
+		return
+	}
+
+	// If this descriptor has a $ref, record it
+	if desc.Ref != "" {
+		referenced[desc.Ref] = true
+	}
+
+	// Walk children
+	for _, child := range desc.Properties {
+		collectRefsFromDescriptor(child, referenced)
+	}
+	if desc.Items != nil {
+		collectRefsFromDescriptor(desc.Items, referenced)
+	}
+	for _, child := range desc.AllOf {
+		collectRefsFromDescriptor(child, referenced)
+	}
+	for _, child := range desc.AnyOf {
+		collectRefsFromDescriptor(child, referenced)
+	}
+	for _, child := range desc.OneOf {
+		collectRefsFromDescriptor(child, referenced)
+	}
+	if desc.AdditionalProps != nil {
+		collectRefsFromDescriptor(desc.AdditionalProps, referenced)
+	}
+}
+
 // operationHasTag returns true if the operation has any of the given tags.
 func operationHasTag(op *OperationDescriptor, tags map[string]bool) bool {
 	if op == nil || op.Spec == nil {

experimental/internal/codegen/filter_test.go

@@ -195,7 +195,7 @@ func TestFilterSchemasByName(t *testing.T) {
 	require.NoError(t, err)
 
 	matcher := NewContentTypeMatcher(DefaultContentTypes())
-	schemas, err := GatherSchemas(doc, matcher)
+	schemas, err := GatherSchemas(doc, matcher, OutputOptions{})
 	require.NoError(t, err)
 
 	// Count component schemas
@@ -228,7 +228,7 @@ func TestFilterSchemasByName_Empty(t *testing.T) {
 	require.NoError(t, err)
 
 	matcher := NewContentTypeMatcher(DefaultContentTypes())
-	schemas, err := GatherSchemas(doc, matcher)
+	schemas, err := GatherSchemas(doc, matcher, OutputOptions{})
 	require.NoError(t, err)
 
 	filtered := FilterSchemasByName(schemas, nil)
@@ -300,6 +300,74 @@ func TestFilterIntegration_GenerateWithExcludeSchemas(t *testing.T) {
 	assert.NotContains(t, code, "type Pet struct")
 }
 
+// TestFilterIntegration_IncludeTagsFiltersSchemas verifies that when include-tags is used,
+// only schemas referenced by the included operations are generated.
+// This is the behavioral test for https://github.com/oapi-codegen/oapi-codegen-exp/issues/3
+func TestFilterIntegration_IncludeTagsFiltersSchemas(t *testing.T) {
+	doc, err := libopenapi.NewDocument([]byte(filterTestSpec))
+	require.NoError(t, err)
+
+	cfg := Configuration{
+		PackageName: "testpkg",
+		Generation: GenerationOptions{
+			Client: true,
+		},
+		OutputOptions: OutputOptions{
+			IncludeTags:              []string{"users"},
+			PruneUnreferencedSchemas: true,
+		},
+	}
+
+	code, err := Generate(doc, []byte(filterTestSpec), cfg)
+	require.NoError(t, err)
+
+	t.Logf("Generated code:\n%s", code)
+
+	// Operations: only ListUsers should be included
+	assert.Contains(t, code, "ListUsers(ctx context.Context")
+	assert.NotContains(t, code, "ListPets(ctx context.Context")
+	assert.NotContains(t, code, "GetSettings(ctx context.Context")
+
+	// Schemas: only User (used by listUsers) should be generated.
+	// Pet and Settings are only used by excluded operations and should NOT be generated.
+	assert.Contains(t, code, "type User struct")
+	assert.NotContains(t, code, "type Pet struct", "Pet schema should not be generated when only 'users' tag is included")
+	assert.NotContains(t, code, "type Settings struct", "Settings schema should not be generated when only 'users' tag is included")
+}
+
+// TestFilterIntegration_ExcludeTagsFiltersSchemas verifies that when exclude-tags is used,
+// schemas only referenced by excluded operations are not generated.
+func TestFilterIntegration_ExcludeTagsFiltersSchemas(t *testing.T) {
+	doc, err := libopenapi.NewDocument([]byte(filterTestSpec))
+	require.NoError(t, err)
+
+	cfg := Configuration{
+		PackageName: "testpkg",
+		Generation: GenerationOptions{
+			Client: true,
+		},
+		OutputOptions: OutputOptions{
+			ExcludeTags:              []string{"admin"},
+			PruneUnreferencedSchemas: true,
+		},
+	}
+
+	code, err := Generate(doc, []byte(filterTestSpec), cfg)
+	require.NoError(t, err)
+
+	t.Logf("Generated code:\n%s", code)
+
+	// Operations: users and pets should be included, admin should not
+	assert.Contains(t, code, "ListUsers(ctx context.Context")
+	assert.Contains(t, code, "ListPets(ctx context.Context")
+	assert.NotContains(t, code, "GetSettings(ctx context.Context")
+
+	// Schemas: User and Pet should be generated, Settings (admin-only) should not
+	assert.Contains(t, code, "type User struct")
+	assert.Contains(t, code, "type Pet struct")
+	assert.NotContains(t, code, "type Settings struct", "Settings schema should not be generated when 'admin' tag is excluded")
+}
+
 func TestFilterIntegration_ServerWithIncludeTags(t *testing.T) {
 	doc, err := libopenapi.NewDocument([]byte(filterTestSpec))
 	require.NoError(t, err)