Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

V2 - Why is OpenAPISchema.Type of type "object"? #1874

Closed
baywet opened this issue Oct 14, 2024 · 4 comments
Closed

V2 - Why is OpenAPISchema.Type of type "object"? #1874

baywet opened this issue Oct 14, 2024 · 4 comments

Comments

@baywet
Copy link
Member

baywet commented Oct 14, 2024

This provides a really poor development experience, forcing the consumer to implement complex type assertions when it shouldn't be required.

And then we do things like those:

Which is not only going to be slow, but also problematic for people using AOT/trimming.

We already know that OAS 3.1 and Json Schema only support the following types:

  • null
  • boolean
  • object
  • array
  • number
  • string

(maybe we could add compatibility with the integer mess).

Why not instead:

  • Define an enum for those types
  • Make the type property, an array/list/enumerable of that enum
  • When serializing as v2/v3, ensuring that we emit the right compatible information.
@darrelmiller
Copy link
Member

I hadn't noticed this. I agree that making the type property of type object is not going to be a great experience. However, I'm not sure making it an array is the right choice considering how commonly devs will only want to set a single value.

Could we make a HttpMethod style class that does some operator overloading to handle assigning both simple values and arrays?

@calebkiage
Copy link
Contributor

According to the doc comments, it says that:

Value MUST be a string in V2 and V3

Is there a situation where it's not a string or an array of strings?

I agree with making it an enum since we know the possible values. We can even add a member for unexpected types and show a validation error.

@baywet
Copy link
Member Author

baywet commented Oct 15, 2024

@darrelmiller with modern CSharp (12) people can simply write collection expressions

schema.Type = [SchemaType.Object];

(assuming we go with an enum)

@calebkiage I think this is simply an abstract of the JSON schema spec at the end, the possible values here being constrained to a set we know in advance, we might as well use an enum.

@baywet
Copy link
Member Author

baywet commented Oct 16, 2024

Interestingly enough STJ chose a flaggable enum, which is another option we haven't considered.
https://github.com/dotnet/runtime/blob/5e9a425ed90f30f92eb3d2d4b25179efe8255232/src/libraries/System.Text.Json/src/System/Text/Json/Schema/JsonSchemaType.cs#L11

They do not have a developer experience requirement though, since everything is internal (and that's too bad since we could have reused a lot of what they've built)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants