Provide a way of avoiding oneOf spec for nullable types

[serganch]

Discussed in #646

Currently Kompendium generates a formally correct but in most cases excessively complicated JSON schema for nullable types.

For example let's have a class:

data class Data(val field: String?)

The generated schema will look like this:

  "Data": {
    "type": "object",
    "properties": {
      "field": {
        "oneOf": [
          {
            "type": "null"
          },
          {
            "type": "string"
          }
        ]
      }
    },
    "required": []
  }

Although technically correct, the oneOf part seems redundant since in Kotlin there is no distinction between the absence of a field and a null value. Thus the following definition is effectively equivalent:

  "Data": {
    "type": "object",
    "properties": {
      "field": {
         "type": "string"
      }
    },
    "required": []
  }

Comparing these two, not only the former is heavier and more verbose, it also causes visualizers like Redoc and Scalar display it in a weird way, significantly reducing readability of the documentation.

So it would be great to have in Kompendium an opt-in setting for simplified schema generation for nullable types

[brizzbuzz]

hmmm sorry if i wasnt clear, since the oneOf implementation is, as far as i can tell, correct... i probably wont change the actual implementation. it would add too many weird gotchas.

i think a good middle ground is to have a way that a kompendium user can say that they want nullables to be marked as "required = false"

[serganch]

hmmm sorry if i wasnt clear, since the oneOf implementation is, as far as i can tell, correct... i probably wont change the actual implementation. it would add too many weird gotchas.

It's up you. This is your creature, so it's you who should decide how things are going to be. :)

i think a good middle ground is to have a way that a kompendium user can say that they want nullables to be marked as "required = false"

Not sure what you mean. The current behavior already makes nullables not required.

[brizzbuzz]

oh... then whats the issue? perhaps im confused. i thought the issue was that your fields were being marked as required, with the value of either null or whatever the type was.

[serganch]

Okay, let's approach this from another direction. Suppose I want to have a schema exactly like this (field is of type string and optional):

  "Data": {
    "type": "object",
    "properties": {
      "field": {
         "type": "string"
      }
    },
    "required": []
  }

How do I achieve this with Kompendium?

1. If I define class Data like this:

data class Data(val field: String)

I'll get

  "Data": {
    "type": "object",
    "properties": {
      "field": {
         "type": "string"
      }
    },
    "required": [ "field" ]
  }

This is not what I want.

2. If I make field nullable:

data class Data(val field: String?)

I'll get

  "Data": {
    "type": "object",
    "properties": {
      "field": {
        "oneOf": [
          {
            "type": "null"
          },
          {
            "type": "string"
          }
        ]
      }
    },
    "required": [ ]
  }

This is not what I want either, and it looks like I'm out of options at this point.

Kotlin itself doesn't give me any way to control field optionality other than type nullability. I could have missed something, but Kompendium also doesn't seem to provide any customization in this respect (like annotations or so).

So, what can I do to meet my goal?

[brizzbuzz]

i mean at a certain point you're just fighting the language no?

because as far as I can tell, Kompendium correctly translates this data class.

so im not sure what to tell you, you may just be stuck with this limitation.

if you want to take a stab at a PR that would be an opt-in way for users to explicitly choose for their schemas to be represented in this way, Ill take a look at it, but i cant for certain say it will get merged because Im not sold that this edge case is worth all the additional complexity this may introduce into the code base.

[serganch]

Ryan, I'm not fighting anything, especially Kotlin, which I love. I'm trying to convince you that Kompendium could be better at some aspects. As I've already mentioned, the Ktor plugin for IDEA (from the inventor of Kotlin BTW) generates schema exactly the way I propose. And, what's most important, that schema perfectly works, unlike Kompendium's schema, even though it technically complies to the specs.

The problem with their generator is that it lacks important features and it's closed source. That's the reason I've started looking for something else. Kompendium has those features, but the way it treats nullables is a true blocker for me.

Sure I'll consider adding a PR, and sure it will be your decision whether to merge it or not :)