Request: Add type parameter to Reference

[rafalkrupinski]

Wherever a Reference is used in OpenAPI, it's clear to us what the referred object type is supposed to be. Adding a type parameter to Reference (and every field that uses it) would make it clear to tools.

If we had schema_or_ref: Schema | Reference[Schema], we could also have a resolver function def resolve_ref[T](obj_or_ref: T| Reference[T]) -> T:... and then schema = resolve_ref(schema_or_ref) gives us a concrete type.

I'd be happy to prepare a PR, if such change is welcome.

[mike-oakley]

Hey @rafalkrupinski! Thanks for reaching out.

References can also be pointing at separate documents as well (e.g. "$ref": "Pet.json") - given this library currently doesn't support loading of local or remote files, what would you propose the behaviour be in this scenario?

[rafalkrupinski]

Which field in OpenAPI refers to a whole file?
I think the target is always a specific entry, for example {"$ref":"pet.json#/components/schemas/Cat"}, so "schema":{"$ref":"..."} must always refer to json schema object, otherwise such description is invalid.

My proposal is about typing the model. I didn't see any $ref resolution code here, but if it's there and doesn't support other files, it should just fail. Regardless, $ref still points to an object of a specific type

OK, I think I get what you meant.

The value of $ref doesn't matter for a field type schema: Schema | Reference[Schema]. If it's {"$ref": "Pet.json"}, the file should have a single JSON Schema object. It's up to a ref resolver to handle the value at runtime.

Regarding ref resolver, above I meant then that users could have such a function in their projects, but perhaps it's a good idea for this project to provide one. I was going to look at referencing library for my project, but I haven't done it yet.

[rafalkrupinski]

I've edited my answer @mike-oakley