Does the "required" attribute on fields apply to Response objects?

[Seven24]

I'm trying to settle a debate with a colleague of mine. I contend that the required attribute should be completely ignored in any Response schema and he contends that it must be honored.

This is not an uncommon situation. One creates a schema with some required fields. References it in various Request payloads (say POST or PUT) as well as in some Response payloads (like a GET).

My argument, beyond common sense, is that the documentation is clear albeit by omission. Nowhere in the section on the Response body does it mention the required attribute but it is mentioned in the Request body section.

My colleague's argument is akin to "math is math" and that required means required even if on the Response object.

For those wondering, the issue is coming up because SalesForce's External Services functionality is throwing a fit when it encounters a Response object with a null but required field. So, the real debate is whether SalesForce's External Services functionality is incorrectly interpreting the OpenAPI spec (my contention) or whether there is an omission in the OpenAPI documentation about honoring the required attribute on fields on Response schemas.

If for some reason, this should be honored (which IMO is crazy), then a needed feature is a way to simply disable the required attribute on a given schema reference.

[handrews]

@Seven24 Schema Objects behave the same no matter where they are. There have been many discussions on the best way to handle variations between request vs response, GET vs PUT vs POST, etc., both in this repository and in the one for Moonwalk (the project for designing OpenAPI 4.0). Here's the most extensive one of which I am aware. It's old but not forgotten- we've been doing some deeper re-thinking of how to organize 4.0 so details have been a bit on hold.

• Context property annotations sig-moonwalk#56

[karenetheridge]

SalesForce's External Services functionality is throwing a fit when it encounters a Response object with a null but required field. So, the real debate is whether SalesForce's External Services functionality is incorrectly interpreting the OpenAPI spec (my contention) or whether there is an omission in the OpenAPI documentation about honoring the required attribute on fields on Response schemas.

If a property is marked as required in the json schema, and it is present with a null value, then it is still present and the required keyword is satisfied.

If this null value is not acceptable to the API, then a restriction needs to be added, such as constraining the property to a specific type (perhaps string, or integer).

Then why is it specifically mentioned in the Request body?

Is it? Do you mean the required keyword here -- https://spec.openapis.org/oas/v3.1.1#fixed-fields-10 ? That's not a json schema keyword, that's an OpenAPI keyword that specifically pertains to request bodies. It's different from any required that may appear below a schema keyword, and the response object (https://spec.openapis.org/oas/v3.1.1#response-object) doesn't have that keyword. (Perhaps it should, as there are valid API responses that don't have bodies, such as "204 No Content".)

...one could easily indicate that the given attribute does not apply to a schema when used with Responses. Without it, this is another scenario where one has to needlessly create duplicative schemas.

That's what $ref is for -- you can define a schema that doesn't contain required, and then use it in multiple places via $ref, and add the required keyword where desired and omit it where it's not.

[handrews]

@Seven24

I made no such implication directed at a person.

People write the spec, so complaining about the decisions made in the writing of the spec means you are complaining about people. It is important to remember that this work is not simply disembodied text on a page.

I cannot imagine a scenario in which that would be desired behavior.

Clearly the success of the OpenAPI Specification suggests otherwise.

As your comments are either about JSON Schema (which should be directed to the JSON Schema project), or are dismissive of the work and perspective of others, I am closing and locking this issue as not productive.

[handrews]

After talking this discussion over with some folks in the project I'm going to try re-opening it.

@Seven24 Please take a moment to think through whether other people might have a different perspective than yours. And that the way things work actually work well for others, and that dismissing them as unreasonable, "crazy", or wrong is dismissing how many people have successfully used the OAS for quite a few years now. And is also hurtful to the many volunteers who have made the OAS possible, and who have tried very hard to balance all of the competing and often irreconcilable demands and perspectives of different people.

Please also keep in mind that we cannot elaborate on everything in the OAS itself. The spec is already very long. We have learn.openapis.org (which has its own repository) specifically to address more topics in depth. That is also mostly volunteer-maintained, so the omission of something there usually means we have not found a volunteer willing and able to write about it.

Please, in general, do not assume that the lack of something indicates that it is not considered important. We could productively employ a staff of 10 or more people to work on the spec and the Learn site, but we do not have the budget to do such things. We are trying our best here, and are looking for collaboration. Confrontation and dismissive language makes it hard to retain volunteers because they feel unappreciated or even like it is more harmful than helpful to contribute. And we need happy volunteers to make this project wor.

[Seven24]

As your comments are either about JSON Schema (which should be directed to the JSON Schema project), or are dismissive of the work and perspective of others

I never made any such implication. I get that the JSON schema is a generalized set of rules which do not know the context in which the JSON payload is used.

And that the way things work actually work well for others, and that dismissing them as unreasonable, "crazy", or wrong is dismissing how many people have successfully used the OAS for quite a few years now.

I really do not understand this warping of what I said. At no time did I claim any person was crazy. Not once. At no time did I dismiss anyone's efforts or contributions at OAS. Not once. At no time did blame I anyone for the implications of the spec. Not once.

Please, in general, do not assume that the lack of something indicates that it is not considered important.

Never once did I make any such implication.

Based on karenetheridge response, I think I see my disconnect. The Required attribute in the OAS Request body is for the body itself not the fields in the body. That apparently means that rules on JSON schema take over and that means that if a Schema has indicated certain attributes are required but one wants that only enforced on a Request body and not in a Response body, one has to create two different Schemas. Is that accurate? Is there a way of referencing the same schema multiple times but indicate in the context of one use (say the Request body) that certain fields are required and in another context (say in a Response body) that those attributes are not required without creating two different schemas?

[ralfhandl]

Correct, there currently is no way to have the same schema interpreted differently in different contexts. As @karenetheridge suggested one can define context-specific schemas that reference the context-independent common parts.

The required keyword in a response schema can be seen as a guarantee to clients that the listed properties will always be present in a well-formed response. If there is no such guarantee, then better not use that keyword in a response schema.