Inline schemas with no ids present problems for client code generation

[fariadev22]

Context
I'm an API specifications expert at APIMatic. For those who might not know APIMatic is heavily involved in auto-generation of client SDKs from API specification formats especially OpenAPI. One of the key problems we've encountered over the years for code generation is handling inline schemas i.e. schemas that don't have a unique id assigned to them.

Problem
In APIMatic, for client code generation purposes, object schemas with known properties are converted into respective model classes in the chosen language. Similarly, enumerations are also converted to enum representations in the chosen language. To perform this conversion a unique code-friendly name is required. This works well for schemas defined globally in OpenAPI v3 with a unique name i.e. under the components/schemas but not so much for inline schemas that have no identifiers.

Our fallback mechanisms for inline schemas involve processing the schema title instead. However, title is not as often used as we'd like or are way too long/not code-friendly enough. The ultimate fallback mechanism we use is to simply auto-generate the name from the closest information available e.g. using the property name if the inline schema definition is found in schema properties or by using the parameter name if the schema is linked to a parameter and so on. However, the names auto-generated this way aren't always user-friendly especially when those names have potential clashes with other such inline schemas (a parameter schema name might clash with a property schema name and so on) and have to be made unique somehow (by appending a number or some other approach).

Suggestion
OpenAPI v4 allows setting a kind of a schema id much like an id for operations (operationId) that are expected to be unique, short and code-friendly. The problem with this approach could be regarding ensuring uniqueness as schemas are generally spread all over the place and even across files. But the naming problem would still be mitigated largely with this approach.

I don't have any other suggestions at the moment but thought to put my ideas out anyway :)

[MikeRalphson]

There was some work done here: https://github.com/json-schema-org/vocab-idl but I believe it has stalled a little.

[fariadev22]

Thanks for sharing! Yeah, doesn't seem to be actively worked upon. But looks quite interesting. It is true that the use of JSON schema as a "validation" structure does create too much flexibility that does not always suit interface/code generation. So this seems to have the right goal in mind.

[handrews]

@fariadev22 In OpenAPI 3.1, you can define schema extensions more easily. Also, while I dislike overloading keywords, you could use $anchor, which assigns plain-name URI fragments to schemas, to also assign code names. The allowable characters for $anchor are close to code-friendly. It does allow things like - and . that you might need to exclude in the guidance you give on this. Of course, anchors are scoped to base URIs (set by $id) so if you are working across multiple schema resources you might end up with the same anchor in different resources. But it could be a starting point.

OAS 3.0 does not support $anchor (or the equivalent in draft-04 JSON Schema).

[fariadev22]

Ahh I didn't realize $anchor could closely achieve the purpose I was looking for. I always feel that most extensions tend to lock you to a vendor whereas a standard feature makes your spec more interoperable. So, this indeed sounds like a good starting point. Thanks!