Nullable properties generate incorrect OpenAPI specification

[jbreton]

Expected Behavior

I updated a project from micronaut 2.5.11 to 3.1.2 and the typescript SDK generator we use stoped working correctly.

The problem is related to how nullable properties are handled.

Given a class with a nullable property like this

data class ParentSchema(
  val child: ChildSchema? = null
)

That class would procude this in micronaut 2.5.11 :

  ParentSchema:
      type: object
      properties:
        child:
          $ref: '#/components/schemas/ChildSchema'

As of micronaut 3.1.2, it will produce :

  ParentSchema:
      type: object
      properties:
        child:
          allOf:
          - $ref: '#/components/schemas/ChildSchema'
          - type: object
            nullable: true

This particular structure cause generators to see this as being a ChildSchema or an object, not a nullable property.

Instead, it should produce something like this :

In OAS 3.0
  ParentSchema:
      type: object
      properties:
        child:
          nullable: true
         oneOf:
         - $ref: '#/components/schemas/ChildSchema'

In OAS 3.1
  ParentSchema:
      type: object
      properties:
        child:
          oneOf:
            - 'null'
            - $ref: '#/components/schemas/ChildSchema'

You can find much more details about nullable properties here.

Actual Behaviour

No response

Steps To Reproduce

No response

Environment Information

No response

Example Application

No response

Version

3.1.2

[jeremyfiel]

I know this is old but the proposed answer is invalid JSON Schema. Is this the way it was implemented?

oneOf: 
   - 'null'  # <--- invalid JSON Schema
   - $ref: '#/components/schemas/ChildSchema'

For OpenAPI 3.1.x, the following syntax should be

oneOf:
  - type: 'null'  # <--THIS
  - $ref: '...'

which can also be written as such: (which may have been the original thought)

child:
  type:
    - 'null'
    - object
  $ref: '...'

---

Another thought I'm having as I write this relates to Nullable in the context of OAS 3.1.x.

This line should never execute because JSON Schema 2020-12 doesn't recognize the nullable keyword and the annotation SHOULDN'T be used. It SHOULD use the type keyword, which is an Assertion in JSON Schema lingo. It looks like the implementation doesn't consider these nuances.

https://www.learnjsonschema.com/2020-12/validation/type/