Repository navigation
Let format be truly optional for integer, add long #162
Description
See swagger-ui issue 644.
I propose that the Swagger 2.0 specification be revised around the use of types. Currently
it reads
Primitives have an optional modifier property format.
but this is imprecise. format is optional for some types but in the current implementation is it required for others. That is, "type" : "integer" is insufficient; one must specify "format" : "int32" or "format" : "int64" as well.
I propose that this be simplified to just
"type" : "integer"
or
"type" : "long"
Having to specify two fields to define the type of an integer property/field is tedious and unnecessarily verbose. It adds dozens of lines to a typical swagger spec (either yaml or json),
Similarly, it makes sense to allow the other "common names" for the value of "type" as an alias for type+format.
I think this would make Swagger 2.0 easier to use for all users.
Activity
webron commentedon Oct 17, 2014
We're following json-schema here.
"format" is never mandatory. As you said in the swagger-ui issue, it's just a bug in that project.
So you can still specify it with a single property, it just needs to be fixed.
fehguy commentedon Oct 17, 2014
yes but creating a new "common name" isn't a great idea, since that is not json schema, nor is it in the spec. I suspect all tooling expects this format for now, and we can consider more friendly "types" for future versions of the spec.
DavidBiesack commentedon Oct 17, 2014
great - can you update the spec to clarify what the default is for "integer" when format is not present? I suspect "int32" but it should be explicitly stated.
(It is still unfortunate that long still requires two fields to specify it, whereas "type" : "long" would be much more convenient and less confusing. (Note that some tools may reorder JSON elements in an object, so "format" : "int64" may become displaced from the type, making a spec potentially confusing)
webron commentedon Oct 17, 2014
Integer is unlimited. Could be int1024 theoretically. It just means a whole number with no fraction. It is as defined by the json schema - http://json-schema.org/latest/json-schema-core.html#anchor8.
Added clarification for missing formats