OAS 3.0 and 3.1 schemas require the Response Object description property but allow it to be empty

[TristanSpeakEasy]

The JSON Schema - https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Response/required for the OpenAPI specification marks description as a required property but then allows it to be an empty string.

This is causing some strange use cases in validators where people are just adding description: "" to get around the error returned.

I would propose either this is removed from being a required property or the property has a min length added (can even just be minLength: 1)

Thoughts?

[TristanSpeakEasy]

Also present in https://spec.openapis.org/oas/3.1/schema/2022-10-07#/$defs/response/required

[handrews]

Thanks, @TristanSpeakEasy! I hope you don't mind me shortening the title a bit for readability. I'm not sure if this schema configuration was intentional (and if so, why) or not but we'll look into it. We're in the middle of fixing our schema deployment process but hopefully we can include any fix for this with other recent schema fixes.

[davidmoten]

What was the motivation for the description field to be marked as required? It certainly doesn't seem that important to a lot of users of OpenAPI 3.x, so making it optional seems like a good choice.

[handrews]

@davidmoten no clue - I've seen at least one TSC member lament that particular requirement. It goes back to at least the 2.0 days which is well before my time.

I suppose we could relax the requirement in 3.2 🤔

[TristanSpeakEasy]

Just to clarify what might happen so we can plan work on our side.

• 3.0.x and 3.1.x schemas will be update to enforce on non-empty description?
• And 3.2.x schemas will potentially remove the requirement for descriptions at all?

[handrews]

@TristanSpeakEasy I'm not quite sure what we want to do here yet. The specification is the source of truth, while the schema is just a tool. It is a best-effort that is intended to accept all valid documents, although there are many errors that it does not (and in most cases, cannot) catch.

I checked the specification, and there is nothing requiring non-empty strings, so that's not going to get changed in the schema. If you want to enforce non-empty strings, I'm afraid that's a job for a linter.

3.2 could have a spec change to make it not required. We can't make a requirement more strict in a patch release, so that's the first place we could do it. Do you want to repurpose this issue for that? (Or file a new one and close this one?)

[darrelmiller]

I would support a v3.2 just for that :-)

[lornajane]

The world would be a better place if responses had useful descriptions!! But agree there's no point in having a required field that can be empty. I'd be open to making it optional (but recommended maybe!) in 3.2 if someone wants to propose that change.