Openapi-specification: Clarify if header is required to be sent in the response

[Maks3w]

Given the headers section has a definition for a given header (let's say ETag) the question is:

Is the header required to be present in the response sent by the server?

headers: A list of headers that are sent with the response.
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#fixed-fields-10

Headers object: Lists the headers that can be sent as part of a response.
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headersObject

Reading the first definition I understand that is _REQUIRED_.
Reading the second definition I understand that is _OPTIONAL_.

Spec should be rephrased clarifying this aspect.

[Maks3w]

IMO should be addressed as _REQUIRED_

[webron]

That's an interesting and fair question. I'll have to dig into the discussions about it to see if we mentioned anything specific about it. However, even the first definition doesn't necessarily mean it is required, but rather suggested. Normally, when something is required, the term MUST is normally used across the spec to mention something is REQUIRED. However, I agree it is not clear enough and should be revised.

[Maks3w]

The argument which I think MUST be REQUIRED is that the header is linked to the response HTTP Code.

So it's specific enough to assume these headers will be received always for this HTTP Code.

[webron]

I'm not disagreeing, but if the intent wasn't clarified originally, I may not be able to clarify it in this version of the spec as well. The current wording implies OPTIONAL over REQUIRED, but as said, I'll look into it.

[nfroidure]

What about a required=true attribute in the headers object definition?
https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#headersObject

I think it strongly depends on each headers type.

[Maks3w]

I only suggest when possible use the same validation rules as JSON-Schema. required: boolean is not a valid attribute.

[nfroidure]

Wasn't aware of the JSON-Schema compliance, but any property indicating the requirement would be great as well.

[nfroidure]

Say, minLength=1 when required ? http://json-schema.org/latest/json-schema-validation.html#anchor25

[Maks3w]

minLength and the rest of those validators are related with the value. i.e if the header value has a minLengh of 1.

[arno-di-loreto]

Totally agree with @nfroidure proposal (add a required property in header object).
We already have that for parameters (headers and non body parameters objects have a lot in common) , why couldn't we have the same thing on returned headers?

[webron]

Parent: #560

[webron]

The Header Object now follows a similar pattern to the Parameter Object and contains a required field which is by default false.