Repository navigation
Clarify if header is required to be sent in the response #321
Description
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-10Headers 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.
Reacted by Arnaud Lauret, Everett Toews, Thomas Maddox and Cameron Taggart
Metadata
Metadata
Assignees
Labels
No labels
Activity
Maks3w commentedon Apr 5, 2015
IMO should be addressed as REQUIRED
webron commentedon Apr 6, 2015
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
MUSTis normally used across the spec to mention something is REQUIRED. However, I agree it is not clear enough and should be revised.[-]Acalaration about if header is required to be sent in the response[/-][+]Aclaration about if header is required to be sent in the response[/+][-]Aclaration about if header is required to be sent in the response[/-][+]Clarify if header is required to be sent in the response[/+]Maks3w commentedon Apr 6, 2015
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 commentedon Apr 6, 2015
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 commentedon Apr 10, 2015
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 commentedon Apr 10, 2015
I only suggest when possible use the same validation rules as JSON-Schema.
required: booleanis not a valid attribute.nfroidure commentedon Apr 10, 2015
Wasn't aware of the JSON-Schema compliance, but any property indicating the requirement would be great as well.
nfroidure commentedon Apr 10, 2015
Say, minLength=1 when required ? http://json-schema.org/latest/json-schema-validation.html#anchor25
Maks3w commentedon Apr 10, 2015
minLengthand the rest of those validators are related with the value. i.e if the header value has a minLengh of 1.arno-di-loreto commentedon May 11, 2016
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 commentedon May 19, 2016
Parent: #560
webron commentedon Mar 3, 2017
The Header Object now follows a similar pattern to the Parameter Object and contains a
requiredfield which is by defaultfalse.cataggar commentedon Aug 25, 2022
@webron, https://swagger.io/specification/v2/ does not show that the
Header Objecthas arequiredfield likeParameter Object. It would be great if it did. I didn't find very many results in my initial search for examples:cataggar commentedon Aug 25, 2022
In the currently spec, a
Header Objectincludes it as it is almost the exact same as aParameter Object.https://spec.openapis.org/oas/latest.html#header-object