Clarify whether inline and reference attributes are mutually exclusive. Usage of nullable and $ref

[sebastien-rosset]

I suggest the OAS spec 3.x clarifies, recommends or provides an example for the following scenario: the value of a property is nullable, and the property type is a reference.

Intuitively, one may think about writing:

type: object
properties:
  address:
    $ref: '#/components/schemas/Address'
    nullable: true

The online validator does not complain this is an invalid OAS, but AFAIK this is not compliant with the spec. My interpretation is this snippet is not compliant with the spec because the OAS spec states:

properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions instead of defining them inline.

However, the spec does not explicitly state in unambiguous terms whether the definition is exclusive or not. I.e. is it possible to combine inline with a reference? It's not very clear, so I wouldn't be surprised if tools exhibit inconsistent behavior.

Related to this, in other parts of the spec, there is a reference to the ABNF syntax, and then the OAS uses "|" to represent an alternative. Shouldn't this be replaced with a solidus "/", per RFC 5234?

Since it does not seem legal to mix a $ref with inline attributes (?), I've seen people using "allOf", "anyOf", or "oneOf". They all seem to work in principle, but imo it would be best to have clear guidelines.

type: object
properties:
  address:
    allOf:
     - $ref: '#/components/schemas/Address'
    nullable: true

type: object
properties:
  address:
    anyOf:
     - $ref: '#/components/schemas/Address'
    nullable: true

type: object
properties:
  address:
    oneOf:
     - $ref: '#/components/schemas/Address'
    nullable: true

One consideration is how the tools generate code. Depending on the language of choice, a nullable type can be programmed as a pointer to a struct/class. It would be cumbersome if inline and reference are mutually exclusive, and OAS authors must use anyOf, allOf, or oneOf when they also want to specify nullable=true. If "anyOf/allOf/oneOf" is added, it will either complicate the generated code, or the code generator must be smart enough to simplify the code.

[sebastien-rosset]

I just found out the same discussion thread is at #1368