`$ref` with `type: null` not properly converted

[mattoni]

Thanks for your work on this project!

I've got a rather complex spec I recently updated to 3.1.0, but need 3.0.3 for some tooling still. I have many places where in order to support a $ref that can be null in 3.1.0, I do this:

However, it is not properly converted (even with --allOf), but instead preserved:

I'd expect to see something like

stack:
  type: object
  nullable: true
  allOf:
    - $ref: ...

Is this something that can be resolved?

[DavidBiesack]

This can probably be resolved, but it is more complicated than your example. For example, the type: 'null' constraint might be buried inside another schema that is also in components/schemas

stack:
  anyOf:
     - $ref: '#/components/schemas/StackSummary'
     - $ref: '#/components/schemas/NullableObject'

NullableObject:
  type: [ object, 'null' ] ## or perhaps just a Nullable schema with type: 'null' ##

or a schema which uses more layers of indirection, any of which may use which or anyOf or oneOf alternatives....

If the scenarios simplify down to a schema with anyOf and one of the alternatives matches just type: null with no other JSON Schema keywords, I think a transformation that removes the type: null and replaces it with nullable: true(removing type: null from the anyOf is quite possible. But if one of those schemas, in addition to type: null, use other keywords such as readOnly or writeOnly, one cannot just discard it.

To be fully robust, an updated should probably handle oneOf in the same way as anyOf.

An alternate way to code an optionally null value in OpenAPI 3.1 is

type:  [ 'object' , 'null' ]

which this tool does recognize. Admittedly, that is often harder to put into the schema definitions due to other uses.

For multiple reasons (code gen etc.) I've avoided using anyOf( or oneOf), so I've not written openapi-down-convert strategies that deal with. Your use of anyOf is perfectly valid though, just "novel" to me.

Thanks for the report, @mattoni

[mattoni]

Thanks for the detailed response! The challenge for me is supporting $refs that can be null, but as a rule of thumb i never make the root component/$ref itself nullable. Obviously there are a lot of possibilities and challenges, but even the simple solution for anyof/oneof would be very beneficial, since i think that's probably a somewhat common scenario.

For reference, my 3.1.0 updated spec can be found here: https://github.com/cycleplatform/api-spec/blob/main/platform/api.yml. It's a very beefy API so might have several interesting things in it, but I'm primarily concerned with removing the type: null and adding nullable to make my spec usable again.

Is this something that you're planning to tackle, or looking for a contributor? Unfortunately my time is pretty restricted right now, otherwise I would have just dove in.

[mattoni]

@DavidBiesack I ended up finding time to work on this, let me know if that covers most/all of your concerns. At the very least should give a decent enough point to leap from!

[8ma10s]

@DavidBiesack There seems to be a new PR #30 that inherits #25 and provides a fix for requested change. Is there any chance we can merge that PR and release a new version?
I'm having issues with properly representing nullable custom schema field in the OAS 3.1 definition while making openapi-down-convert work properly.

[DavidBiesack]

@8ma10s I'll take a look at this when I get a chance