Support setting fields as optional by default (#947)

Author: wolveix

api.go

@@ -215,6 +215,11 @@ type Config struct {
 	// for example if you need access to the path settings that may be changed
 	// by the user after the defaults have been set.
 	CreateHooks []func(Config) Config
+
+	// FieldsOptionalByDefault controls whether schema fields are treated as
+	// optional by default. When false, fields are marked as required unless
+	// they have the omitempty or omitzero tag.
+	FieldsOptionalByDefault bool
 }
 
 // API represents a Huma API wrapping a specific router.
@@ -410,6 +415,9 @@ func NewAPI(config Config, a Adapter) API {
 	if config.Components.Schemas == nil {
 		config.Components.Schemas = NewMapRegistry("#/components/schemas/", DefaultSchemaNamer)
 	}
+	if mr, ok := config.Components.Schemas.(*mapRegistry); ok {
+		mr.fieldsOptionalByDefault = config.FieldsOptionalByDefault
+	}
 
 	if config.DefaultFormat == "" && !config.NoFormatFallback {
 		if config.Formats["application/json"].Marshal != nil {

huma_test.go

@@ -3354,7 +3354,7 @@ func TestCustomValidationErrorStatus(t *testing.T) {
 // 	})
 // }
 
-func globalHandler(ctx context.Context, input *struct {
+func globalHandler(_ context.Context, input *struct {
 	Count int `query:"count"`
 }) (*struct{ Body int }, error) {
 	return &struct{ Body int }{Body: input.Count * 3 / 2}, nil
@@ -3409,3 +3409,54 @@ func TestGenerateFuncsPanicWithDescriptiveMessage(t *testing.T) {
 	})
 
 }
+
+func TestFieldsOptionalByDefault(t *testing.T) {
+	type MyInput struct {
+		Body struct {
+			Name string `json:"name"`
+			Age  int    `json:"age" required:"true"`
+		}
+	}
+
+	// Default behavior.
+	{
+		config := huma.DefaultConfig("Test", "1.0.0")
+		config.FieldsOptionalByDefault = false
+		_, api := humatest.New(t, config)
+
+		huma.Post(api, "/test", func(ctx context.Context, input *MyInput) (*struct{}, error) {
+			return nil, nil
+		})
+
+		// Missing name should fail because it's required by default.
+		resp := api.Post("/test", map[string]any{
+			"age": 25,
+		})
+		assert.Equal(t, http.StatusUnprocessableEntity, resp.Code)
+		assert.Contains(t, resp.Body.String(), "required property name")
+	}
+
+	// Mark fields optional by default.
+	{
+		config := huma.DefaultConfig("Test", "1.0.0")
+		config.FieldsOptionalByDefault = true
+		_, api := humatest.New(t, config)
+
+		huma.Post(api, "/test", func(ctx context.Context, input *MyInput) (*struct{}, error) {
+			return nil, nil
+		})
+
+		// Missing name should pass because it's optional by default.
+		resp := api.Post("/test", map[string]any{
+			"age": 25,
+		})
+		assert.Equal(t, http.StatusNoContent, resp.Code)
+
+		// Missing age should still fail because it's explicitly marked as required.
+		resp = api.Post("/test", map[string]any{
+			"name": "John",
+		})
+		assert.Equal(t, http.StatusUnprocessableEntity, resp.Code)
+		assert.Contains(t, resp.Body.String(), "required property age")
+	}
+}

registry.go

@@ -20,6 +20,7 @@ type Registry interface {
 	TypeFromRef(ref string) reflect.Type
 	Map() map[string]*Schema
 	RegisterTypeAlias(t reflect.Type, alias reflect.Type)
+	FieldsOptionalByDefault() bool
 }
 
 // DefaultSchemaNamer provides schema names for types. It uses the type name
@@ -60,12 +61,17 @@ func DefaultSchemaNamer(t reflect.Type, hint string) string {
 }
 
 type mapRegistry struct {
-	prefix  string
-	schemas map[string]*Schema
-	types   map[string]reflect.Type
-	seen    map[reflect.Type]bool
-	namer   func(reflect.Type, string) string
-	aliases map[reflect.Type]reflect.Type
+	prefix                  string
+	schemas                 map[string]*Schema
+	types                   map[string]reflect.Type
+	seen                    map[reflect.Type]bool
+	namer                   func(reflect.Type, string) string
+	aliases                 map[reflect.Type]reflect.Type
+	fieldsOptionalByDefault bool
+}
+
+func (r *mapRegistry) FieldsOptionalByDefault() bool {
+	return r.fieldsOptionalByDefault
 }
 
 func (r *mapRegistry) Schema(t reflect.Type, allowRef bool, hint string) *Schema {
@@ -164,11 +170,12 @@ func (r *mapRegistry) RegisterTypeAlias(t reflect.Type, alias reflect.Type) {
 // returns references to them using the given prefix.
 func NewMapRegistry(prefix string, namer func(t reflect.Type, hint string) string) Registry {
 	return &mapRegistry{
-		prefix:  prefix,
-		schemas: map[string]*Schema{},
-		types:   map[string]reflect.Type{},
-		seen:    map[reflect.Type]bool{},
-		aliases: map[reflect.Type]reflect.Type{},
-		namer:   namer,
+		prefix:                  prefix,
+		schemas:                 map[string]*Schema{},
+		types:                   map[string]reflect.Type{},
+		seen:                    map[reflect.Type]bool{},
+		aliases:                 map[reflect.Type]reflect.Type{},
+		namer:                   namer,
+		fieldsOptionalByDefault: false,
 	}
 }

schema.go

@@ -844,10 +844,10 @@ func schemaFromType(r Registry, t reflect.Type) *Schema {
 			fieldSet[f.Name] = struct{}{}
 
 			// Controls whether the field is required or not. All fields start as
-			// required, then can be made optional with the `omitempty` JSON tag,
-			// `omitzero` JSON tag, or it can be overridden manually via the
-			// `required` tag.
-			fieldRequired := true
+			// required (unless the registry says otherwise), then can be made
+			// optional with the `omitempty` JSON tag, `omitzero` JSON tag, or it
+			// can be overridden manually via the `required` tag.
+			fieldRequired := !r.FieldsOptionalByDefault()
 
 			name := f.Name
 			if j := f.Tag.Get("json"); j != "" {