Potentially Nasty Ambiguity about huma

[mtiller]

Note, this is somewhat related to #37. The fact that schemas get merged component by component leads to this situation where the same schema, used in to different places in the API, gets a different name even though the underlying schema is the same. I think maintaining a registration of discovered schemas across all types components would eliminate this. The full name (t.PkgPath()+t.Name()) can serve as a fully qualified name that is unique. By having a registry of schemas, we can a) support $ref and b) avoid the duplication mentioned in #37.

Is there interest in addressing this?

[mt35-rs]

A quick followup. I implemented this. I have a single function in the the schema package that takes a reflect.Type and returns a string representation. To continue with the current behavior, that function could be implemented to return simple t.Name(). But since I have gone through and identified all places where t.Name() was previously used and replaced them with calls to schema.SchemaName(t), now we can try different name strategies by changing only a single line of code.

What I've found is that returning fmt.Sprintf("%s.%s", strings.ReplaceAll(t.PkgPath(), "/", "$"), t.Name()) works quite well. There is no issue with keeping the / characters in there from an OpenAPI perspective. But what I found is that there are several places where $refs are inserted of the form ./<SchemaName> and if you have /s in the <SchemaName>, they don't resolve properly. But by replacing them with $s things work ok.

I ran the generated openapi.json through both restish and oazapfts just to ensure those tools don't trip on anything. Things look good. There are a few cases where $refs get replaced with . that could trip things up.

To be honest, I think a separate refactoring to keep a catalog of schemas (as they are generated) would be better. Currently these are collected on a resource by resource basis which seems to be creating circumstances where you end up (when merging the spec together) with multiple schemas with the same name (even with the disambiguation I'm talking about here). An API wide registry would be better I think but the current approach seems to work nonetheless.

You can find the implementation using t.PkgPath() here. If you are OK with this, I'll submit this as an additional PR.

Comments?

[danielgtaylor]

Thanks, I will look into this issue and the PR ASAP!

[mt35-rs]

Just to be clear, the PR #86 is not a fix for this. That PR completes a feature I added with a previous PR (corner case I hadn't really observed previously). This is another issue although still related to how schemas are managed. I don't have a PR per se but I've published changes that address this to a limited extent. If you want that as a PR, I can certainly submit it. But as I pointed out with my reference to #37, there is a deeper issue here with not having a "global" registry of schemas so it might be better to dig a bit deeper formulate a global registry of schemas to solve both #37 and #87 (this issue).

[mt35-rs]

(sorry it is confusing that I'm both @mtiller and @mt35-rs, it all depends on whether I'm on my work computer or home computer)

[danielgtaylor]

This was partially resolved in Huma v1 and the registry/schema system was reworked in v2. If you continue to use the same names for structs between different packages, you can now provide a custom schema namer function and resolve that however you like, e.g. by using the full package + struct name.