NJsonSchema generates discriminator syntax which is not AsyncAPI compatible

Question

NJsonSchema generates discriminator syntax which is not AsyncAPI compatible

liam-careerhub opened this issue 3 years ago · comments

According to the spec, AsyncAPI should have a discriminator as a string,
https://www.asyncapi.com/docs/specifications/v2.1.0#schemaObject

However, NJsonSchema generates an object instead with a propertyName and mappings fields, which is valid according to the OpenAPI spec

https://github.com/RicoSuter/NJsonSchema/blob/288eb13e931562264ed9ddd12a83741c67a1ddc4/src/NJsonSchema/OpenApiDiscriminator.cs

https://swagger.io/specification/#discriminator-object

This means that Saunter generates invalid AsyncAPI code.

If you call iPetSchema.ToJson() one line 145 in the following file, you'll see the generated JSON and how it doesn't match the requirements:
https://github.com/tehmantra/saunter/blob/main/test/Saunter.Tests/Generation/SchemaGeneration/SchemaGenerationTests.cs

I've reverted to 0.4.0 for now as it's the last version of Saunter with working discriminator support.

I can't see an obvious way to adjust the generated schema in NJsonSchema, maybe this is something @RicoSuter can help with?

Let me know if there's any more information I can provide.

Michael Wildman · Answer 1 · Wed Aug 18 2021 13:26:10 GMT+0800 (China Standard Time)

More frustrations with the different schema formats 😞
There is quite a lengthy discussion in #103 about the correct way to represent nulls, and now we have more issues with the discriminator...

@RicoSuter it seems like we might need to have a specific format for AsyncAPI
I know we have the SchemaType enum, but it seems like this would have to be added directly into NJsonSchema. Is there a way we can support a custom serialization output without having to build it directly into NJsonSchema?

Thanks for your help.

Liam · Answer 2 · Thu Aug 19 2021 07:33:44 GMT+0800 (China Standard Time)

Yeah, I noticed the null issues too, where the generated schema has a lot of null values with the AsyncAPI UI doesn't like.

Maybe the best solution to this is to create a fork of NJsonSchema specifically for AsyncAPI? That is unless @RicoSuter thinks these customisations should be in NJsonSchema itself. That way you can take advantage of development in that project and curate how that merges into the AsyncApi variant?

Either that or NJsonSchema's serialiser would need to be completely customisable (if it isn't already, my knowledge is limited here.)

I think this project (Saunter) has huge potential, I'm a big fan of Swashbuckle and an AsyncAPI equivalent is something which I think is hugely valuable.

Let's see what Rico says I guess.

Rico Suter · Answer 3 · Tue Nov 02 2021 23:06:14 GMT+0800 (China Standard Time)

Can someone clarify what the correct null handling should be?

Is it the same as with OpenAPI or JSON Schema or again completely different?

I'm fine adding the AsyncAPI enum, had to do this for OpenAPI/Swagger as well because it's not just a simple rename of a property but the schema generator needs to generate "completely different" schemas...

Michael Wildman · Answer 4 · Fri Nov 05 2021 03:20:01 GMT+0800 (China Standard Time)

Thanks for replying @RicoSuter :)

In this case the issue is how to support polymorphism.

AsyncAPI uses a field called discriminator - https://www.asyncapi.com/docs/specifications/v2.2.0#schemaObject
OpenAPI uses a discriminator object - https://swagger.io/specification/#discriminator-object
Json Schema has nothing

For representing nullables.
As of today AsyncAPI is JsonSchema-draft-07 compatible, which means we need to do:
For simple/primitive properties:

properties:
  foo:
    type: [string, 'null']

For references to other schema:

properties:
  foo:
    oneOf:
    - type: 'null'
    - '$ref': '#/components/schemas/foo'

Once AysncAPI supports later versions of JsonSchema, we can use $ref and type together.
asyncapi/spec#596

properties:
  foo:
    type: [ object, 'null' ]
    '$ref': '#/components/schemas/foo'

It seems like the discriminator issue alone is enough to force us to implement a different SchemaType in NJsonSchema?

Rico Suter · Answer 5 · Wed Nov 24 2021 05:45:57 GMT+0800 (China Standard Time)

It seems like the discriminator issue alone is enough to force us to implement a different SchemaType in NJsonSchema?

So we would add AsyncApi2 (and later AsyncApi3) or just AsyncApi as new SchemaType?

Michael Wildman · Answer 6 · Wed Nov 24 2021 08:29:44 GMT+0800 (China Standard Time)

That seems like the most appropriate option :)
Given we currently have values like SchemaType.OpenApi3 and SchemaType.Swagger2, it wouldn't be crazy to have SchemaType.AsyncApi2.

Alternative might be to have NJsonSchema allow custom SchemaTypes somehow?
But I'd be fine with just adding SchemaType.AsyncApi2.

Would you like me to work on this and submit a PR to NJsonSchema?

Rico Suter · Answer 7 · Thu Nov 25 2021 07:11:21 GMT+0800 (China Standard Time)

Alternative might be to have NJsonSchema allow custom SchemaTypes somehow?

problem is that njs needs specific code based on the schema anyway, no? Here for example a different inheritance generation.. another option is that you inherit from JsonSchemaGenerator and tweak the behavior with overrides.. that would be nicer in general (ie get rid of the schematype)