#638: Add support of propertyNames

[superstas]

Hi there!

This PR adds support for propertyNames, as discussed in #638.

At the moment, it is supported only when set explicitly on huma.Schema.
Automatically generating propertyNames from map key types requires a separate discussion.

Example

var (
	_ huma.SchemaTransformer = Key("")
	_ huma.SchemaTransformer = Value("")
)

type (
	Key    string
	Value  string
	Values map[Key]Value
)

func (k Key) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	min, max := 1, 10
	s.Description = "A key for a map."
	s.MinLength = &min
	s.MaxLength = &max
	return s
}

func (v Value) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	min, max := 1, 32
	s.Description = "A value for a map."
	s.MinLength = &min
	s.MaxLength = &max

	return s
}

func (v Values) Schema(r huma.Registry) *huma.Schema {
	return &huma.Schema{
		Type:                 huma.TypeObject,
		PropertyNames:        r.Schema(reflect.TypeFor[Key](), false, ""),
		AdditionalProperties: r.Schema(reflect.TypeFor[Value](), true, ""),
	}
}

var _ huma.SchemaProvider = Values{}

type Input struct {
	Body struct {
		Values Values `json:"values"`
	}
}

type Output struct {
	Body struct {
		Message string `json:"message"`
	}
}

func addRoutes(api huma.API) {
	huma.Post(api, "/input", func(ctx context.Context, input *Input) (*Output, error) {
		resp := &Output{}
		resp.Body.Message = "It works!"
		return resp, nil
	})
}

generates

...
    InputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/InputBody.json
          format: uri
          readOnly: true
          type: string
        values:
          additionalProperties:
            description: A value for a map.
            maxLength: 32
            minLength: 1
            type: string
          propertyNames:
            description: A key for a map.
            maxLength: 10
            minLength: 1
            type: string
          type: object
      required:
        - values
      type: object
...

Thank you.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.23%. Comparing base (9d0a320) to head (24aae35).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1100      +/-   ##
==========================================
+ Coverage   93.20%   93.23%   +0.02%     
==========================================
  Files          23       23              
  Lines        4988     5009      +21     
==========================================
+ Hits         4649     4670      +21     
  Misses        272      272              
  Partials       67       67              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds first-class JSON Schema propertyNames support to Huma schemas, enabling validation and schema generation for map/object key constraints (notably for OpenAPI 3.1), with appropriate OpenAPI 3.0 downgrade behavior.

Changes:

• Add PropertyNames to huma.Schema, ensure it is preserved through schema generation and JSON marshaling, and precompute nested validation messages.
• Enforce propertyNames validation for object/map inputs during request validation (including map[string]any and map[any]any with string keys).
• Ensure propertyNames is removed when downgrading specs to OpenAPI 3.0, and extend tests for validation, marshaling, downgrade, and autopatch optionalization.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
validate.go	Validates propertyNames against each object/map key during runtime validation.
validate_test.go	Adds coverage for propertyNames validation behavior and error reporting.
schema.go	Adds Schema.PropertyNames, includes it in JSON output, and precomputes nested messages.
schema_test.go	Verifies propertyNames survives schema provider/transformer generation and marshaling.
openapi.go	Drops propertyNames when downgrading from OAS 3.1 to 3.0.
openapi_test.go	Extends downgrade test inputs to include propertyNames.
autopatch/autopatch.go	Ensures PropertyNames is recursively optionalized by autopatch.
autopatch/autopatch_test.go	Tests optional schema generation preserves PropertyNames.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.