Implement better deduping of schema names when using anonymous structs for request bodies

[mzhu22]

Hi!

I ran into a panic: duplicate name: Request ... error when generating the OpenAPI spec in my API. I noticed this happens when I have >1 POST endpoint taking a request body, where the handler defines the input type via an anonymous struct.

e.g..

func handler1(ctx context.Context, input *struct{ Body {...} }) { ... }
func handler2(ctx context.Context, input *struct{ Body {...} }) { ... }

It seems like the issue is that, when using anonymous structs for request bodies, the OpenAPI schema for the request body gets a generic name "Request". When there's more than one, a collision occurs.

Would it be possible to make a unique dynamic name, e.g., by prefixing with the endpoint path, name, etc?

I know that using named structs is an easy workaround, but I think anonymous structs work well for these input types, since they are not passed around or initialized in other code. It keeps the code concise and avoids another thing to name and rename!

Thanks! Been really enjoying this package. You're doing great work.

[danielgtaylor]

@mzhu22 thanks for opening an issue. Do you have an example of how you are actually running into this problem? Here's an example with anonymous structs that doesn't panic: https://go.dev/play/p/LC0bGxGe1NI

This is a surprisingly complex problem you've wandered into! The current behavior is a deliberate design choice to keep the implementation both simple and reproducible without breaking generated clients (something we ran into with Huma v1 which used unique generated suffixes). Part of the problem is that the order of processing structs can be dependent on a number of things, like the Go version or new structs for new operations that would shift the two that were previously there. For a concrete example, imagine:

type First struct {
  Body struct { /* ... */ }
}

type Second struct {
  Body struct { /* ... */ }
}

You would presumably generate RequestBody1 for First and then RequestBody2 for Second. Your generated SDK would have a call like client.FirstOperation(ctx, sdk.RequestBody1{ /* ... */ }). Now you introduce:

type Another struct {
  Body struct { /* ... */ }
}

Since that may get processed before First, you now get RequestBody1 meaning Another.Body instead of First.Body, breaking the generated SDK. Your users would have to update to using client.FirstOperation(ctx, sdk.RequestBody2{ /* ... */ }).

BTW, we do the same thing with imports from other packages. To keep the generated names simple, the package name is not included, so pacakge1.Model vs. package2.Model will also result in an error. The simple workaround is to rename the type with a local alias or use the nameHint struct tag.

type Example struct {
  Body struct { /* .. */ } `nameHint:"MyBody"`
}

Anyway, you are welcome to customize how all of this works, there is huma.DefaultSchemaNamer which can be overridden and a custom implementation could keep track of names that were seen and create suffixes if you wanted. See https://github.com/danielgtaylor/huma/blob/main/registry.go#L25-L60.

Hope this makes sense and helps!

[mzhu22]

Gotcha, thanks! Lemme look into it further and come up a repro that doesn't have all of our proprietary code and whatnot in it.

Agreed that deduping based on order would not be ideal. I was thinking you could come up with stable unique name by using the endpoint path or something like that. E.g., the request schema for POST /my/path being MyPathRequestBody

[mzhu22]

@danielgtaylor here's a repro! Seems like the conditions are:

1. Use huma.Register to register endpoints with anonymous struct inputs -> request body is named Request in OpenAPI
2. Two endpoints must have request bodies with different shapes (if they're identical in shape, seems like the registry can point them to the same schema).

https://go.dev/play/p/Sls5EzL0-h-

[danielgtaylor]

@mzhu22 thanks for the example! I think this only happens if you are missing the operation ID, for example this works: https://go.dev/play/p/6vWUT6yuVxp.

[mzhu22]

Ooo interesting. Okay thank you! Maybe the issue then is that the behavior isn't very obvious. I imagine that making the operation ID required isn't feasible now, but just trying to brainstorm

[mzhu22]

I'm gonna close this out since my immediate issue was solved. But perhaps adding a strong recommendation in the docs (in the code and the website) to include Operation ID would be helpful, or maybe explaining how Operation ID is used in the spec generation. Thanks again!