Allow more attributes for "Reference Object"

[Amit-XMPie]

Hi,

I'm adopting OAS 3.1.1 now (creation), and I'm pleased that for "Reference Object" you added overriding the "summary" and "description", but this is not enough, as other attributes should also be overridden, like readOnly, writeOnly, etc.
actually, the fact you removed the attribute "nullable" (in favor of the type "null"), is not good, as I like to override this in the "Reference Object" as well.
let me explain why:
while I'd like to define a complex type only once when I use it as a reference for example as a parameter to a method (path), I'd like to say that in this case, it can be "null", or "readOnly", or "writeOnly", but it is not in general "null", "readOnly" or "writeOnly", exactly as now I can have a different "description".
BTW: The same goes for the default value, example(s), which can be different depending on the usage and not related to the type itself (especially the default, where depending on its usage it can be different, like in enum types).

another remark:
I used to simulate it by "inheriting", i.e. creating a new schema, with "allOf" as the "Reference Object", and adding all properties that I like to override without specifying the actual schema (as it is inherited by "allOf"), but now that "nullable" is a type. I can't do this trick anymore, as I can't override the type (there is no sense overriding type when "inheriting").
furthermore, this trick does not work anymore for enum types (yet another "complex" schema that should not be defined several times, as it causes other issues).

please please consider this request, as it is absolutely useful, and it makes version 3.0.x + my trick better that 3.1.x

[hkosova]

the fact you removed the attribute "nullable" (in favor of the type "null"), is not good, as I like to override this in the "Reference Object" as well.

To make a schema reference nullable in OpenAPI 3.1, use this anyOf construct:

prop:
  anyOf:
    - type: 'null'
    - $ref: '#/components/schemas/MyObject'

[Amit-XMPie]

I checked it, but the OAS consumer ignored the additional "- type: 'null'". and rightfully so, as by definition reference object ($ref) as you defined in the "anyOf", can only override the "description" and "summary" see https://spec.openapis.org/oas/v3.1.1.html#reference-object.
also:
prop:

• type: 'null'
  anyOf:
  -$ref: '#/components/schemas/MyObject'

will not work, as it will override a type that is not reasonable.

but in OAS 3:
prop:

• nuallable: true
  anyOf:
  -$ref: '#/components/schemas/MyObject'

would work as it is just an additional attribute.

[Amit-XMPie]

Let me put the request in different words:
This is perfectly alright that a “Schema Object” will conform with the “JSON Schema Specification” and a nullable object will be defined with an additional type “null”.
But a “Reference Object” need to be extended from:

• $ref
• summary
• description

to:

• $ref
• summary
• description
• default
• nullable
• readOnly
• writeOnly
• examples

So, while I define a complex object in Schema, I can define its default, examples, readOnly, writeOnly, or if it is nullable in its usage. Same as I’m happy to do with the summary and description.

[karenetheridge]

What does nullable mean in an object other than a schema? null is a json schema concept, not an OpenAPI concept.

[Amit-XMPie]

The discussion went further, but just for the sake of your question:
nullable did exist as part of OAS 3, so it was an OpenAPI concept, and important one. as when exposing API using OAS, on the other side there are code generators, one example is VS C# Rest API client generator. this generator, among other things, validate something not to be null if not marked as "nullable", and if API producer (like me), would like to be able to fetch\recieve something that can be null, the way to do it, is mark it as "nullable".
the discussion was how can it be done in the new OAS 3.1, where the "nullable" was removed. and how to do it, is what was discussed further in this thread. so anyone that like to understand, should continue the reading. but the short answer is that a "null" type should be added as "one of" the possible types, but the VS C# generator (NSWag) still does not support OAS 3.1, and hence it is not supported yet in this client generator.

[handrews]

@karenetheridge 'nullable' was only ever a field in the Schema Object, albeit one that was defined by the OAS.

[handrews]

@Amit-XMPie in OAS 3.1 the Schema Object $ref is distinct from the Reference Object $ref. The Schema Object $ref behaves according to JSON Schema draft 2020-12. It allows any JSON Schema keyword to be adjacent, but $ref is just a keyword that propagates the results of the referenced schema. These results are combined with other keyword results like any other keyword. There is no override or merge.

In OAS 3.0, nullable only applies to an adjacent type (just like exclusiveMinimum only applies to an adjacent minimum), not to type definitoins in other subschemas (although tooling support is highly variable as this was not clear until 3.0.3).

For modeling inheritance, JSON Schema is a constraint system, which requires a different mindset from a data definition system- you have to start with the least constrained schema as your re-usable base, and layer on more constraints. You cannot lift a constraint once added.

Beyond that, OpenAPI and JSON Schema are separate projects, and requests for changes to JSON Schema should be directed to that project. I don't see anything for the OpenAPI project to do here.

[Amit-XMPie]

I'm not sure if I understand your answer.
As I said I'm exposing my API in OAS, so it is a real life senario and not theoretical.
I presume OAS should fit in the real world and not just for the books.
let me give you an example, and you can show me how to express it in OAS (if possible, then I will be happy).

attached is 4 OAS in JSON format, both the 3.1.1 do not work, both the 3.0.3 does work, with a major consumer of OAS which is Microsoft Visual Studio. you can test it your oas-3-0-3 + trick = working.json

the senario explanation is:

let's say I create a complex model (as for simple types it is irrelevant), lets for the sake of example say it is called "networkDevice" and it has the properties "ip4Address", "ip6Address", "type", "description", etc.
let's say it is identified with its Name (Netbios name).
now let say I like to create 2 simple APIs to manage that, a getter and setter:

• POST /mypai/network-device/name + body of the model, created a new device identified by the name
• GET /mypai/network-device/name, gets a device by its name, or null if there is no device identified by that name

so in OAS I will define a schema for the "networkDevice" model, and it is of type "object" but not null, as when it is used in the POST, I do not like to get a null object.
but on the GET I do like to add to the OAS that the returned object might be null (if not found).

i have examples for the other requests attribues (default, readOnly, writeOnly)
if you like to get feedback from real life senarios, here i m. if you don't and you create OAS just for the books, good luck with that.

oas-3-0-3 = working.json
oas-3-1-1 + trick = not working.json
oas-3-1-1 = not working.json
oas-3-0-3 + trick = working.json

[karenetheridge]

As I said I'm exposing my API in OAS, so it is a real life senario and not theoretical.
I presume OAS should fit in the real world and not just for the books.

Please try to be a little more respectful with your responses. Many of us use OpenAPI in professional contexts so it is not fair to characterize it as theoretical and "just for the books".

[Amit-XMPie]

I will assume that the issue is with the Microsoft Visual Studio OAS consumer (code generator), and not with the OAS definition, as when I add back the "nullable", even though it is marked as OAS 3.1.1, it is working as expected.
I will instruct our customers to prefer OAS 3.0.3 for now (as we support all versions anyhow).

[handrews]

Also, the oneOf construct officially works in more complex arrangements than immediately adjacent to the type keyword, while nullable only works that way in some tools but not in others. So the 3.1 solution is more portable and interoperable than a non-type-adjacent nullable in 3.0.

[Amit-XMPie]

first, let me say, I'm testing using 3 main OAS clients, Swagger UI, Postman, and MS VS code generators, to test my OAS for our APIs, if those work, I'm happy. it was frustrating that some did not worked out with the new OAS 3.1, hence my emotions.
i did initial test with the "oneOf" instead of the "allOf", this made things much better (thanks), but VS still Swagger had issues with the example, showing null, I played around and found that if I put both types in the ref i.e. ['null', 'object'] and not just 'null', that resolved it from Swagger, still VS had issues with enum types. after more playing around I found out I do not need anyOf or allOf at all, simply put the types as part of the ref schema, but I needed to put both types and nullable (for VS).

[darrelmiller]

I am guessing by "MS VS Code generators" you are referring to the bundled version of NSwag. As far as I know, none of the .NET code generators have v3.1 support yet. We just released a preview of the OpenAPI.NET library that supports 3.1, but we haven't updated Kiota yet.

To reiterate what Henry was saying, in v3.1 a $ref inside a Schema is not the same as a $ref inside any other OpenAPI object. When referencing a schema, you can have any JSON schema keyword alongside a $ref. The limit to using summary and description is only for objects other than schema objects.

And, as Henry says, nullable is not supported in OAS 3.1 because it is no longer needed. For your scenario, using oneOf to represent a union type is the right solution. Whether tooling support it yet, is a different matter.

[Amit-XMPie]

Thanks for the information.
The fact that NSwag does not support 3.1 explains a lot. so I will have to wait for it, as this is one of our clients' more common API proxy generators.
The explanation about the $ref inside a Schema, which is not the same as a $ref inside any other OpenAPI object, is the critical information I was missing.
That means all my requests for adding "readOnly", "writeOnly", etc. are already available, as it simply adds them as part of the schema referance object.
That also means I can override the "type", and that explains the replacements for nullable. (in my tests it requires both "null" and "object")

That also means I do not need to do the "oneOf" trick (or "allOf" which I do use in other cases to do inheritance) and actually override all what I need in the Schema Referance Object.

I think between NSWag not supporting 3.1, and $ref inside a Schema, I now understand, and this can be closed. sorry for my emotions. and thanks for your patience and explanations.

BTW: according to this information, and for the sake of completeness, I have attached a revised 3.1 of the sample I used, working in Swagger and Postman but not in NSwag (as expected).
oas-3-1-1 sample.json

[handrews]

@Amit-XMPie

That means all my requests for adding "readOnly", "writeOnly", etc. are already available, as it simply adds them as part of the schema referance object.

Yes, this is correct in 3.1, and applications are free to interpret those annotation keywords however they want.

That also means I can override the "type", and that explains the replacements for nullable. (in my tests it requires both "null" and "object")

An adjacent keyword is not an override- I might be misinterpreting you in which case please disregard the rest, but just in case: type is a validation keyword, and validation results are always AND-ed unless a keyword like 'oneOfspecifically defines a different process (foroneOf, it's exclusive-or). A single type` keyword with the array syntax is effectively an OR of types- that is another keyword-specific exception to the AND rule.

So if you want to add a type, you need to either have both in the same type keyword ({"type": ["object", "null"]}) or use a keyword like oneOf or anyOf that does an OR of some sort ({"oneOf": [{"type": "object"}, {"type": "null"}]}). Otherwise you can only further restrict your constraints, and ANDing type: object and type: "null" makes everything fail.