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

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.

@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!