-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Observations on type primitives #5
Comments
Comment by webron from Sunday Mar 02, 2014 at 14:18 GMT Regarding Regarding the As for the additional number of bits and signed/unsigned property - I disagree with you. Again, most development languages have a distinction between 32bit and 64bit numbers, and the min/max limitations are meant as validation restrictions and not type restrictions. Granted, you can let the client choose whatever data type and limit if you want to limit to 32bits you can use the min/max values always to denote it, but I think that would lead to a more messy resulting swagger spec output rather than simply denoting the type (again, like most development languages do anyways). |
Comment by quasipedia from Sunday Mar 02, 2014 at 23:02 GMT @webron - Thanks for looking into this.
|
Comment by webron from Monday Mar 03, 2014 at 12:37 GMT I disagree with a few of the points you raise (especially the The thing is this - we can hide behind technical jargon all we want but let's look at a practical point of view for a moment. Say I write a REST API in.. say.. Java. Now, if I go and declare an API operation that accepts an integer (int32 in this case), if a client sent me a long (int64) number (that is, something that's more than int32) that would simply not work and I would end up throwing some error. Regarding the usage of I did check a few API descriptions out there, and I consider them to be a problem in many cases. Some state that a field is a That said, I do think you raise valid points, and would love to hear the input of others as well. |
Comment by quasipedia from Monday Mar 03, 2014 at 21:25 GMT Hi @webron! ...as I said... in the end we might have to end up agreeing to disagree. :) I don't think that having to specify limits (if you want to do just that) does clutter the API, honestly. For example, in the framework I created in python, I mapped all native datatypes (both the JSON-Schema's and python's ones) to classes which are subclassed by a generic The framework itself will do the heavy lifting of creating a model with all the right object attributes, and - most importantly - all that a user inspecting that specific Also, if you look at RAML and Blueprint, you will appreciate their approach is similar to the one I am advocating for (not my solution with classes, but my idea that an API specification is not the right place for stuff like And with this, your honour, I rest my case! [ but me too would be interested to hear what other people think about this] Best regards! |
Parent issue: #579. |
Potentially related to #607. |
Tackling PR: #741 |
I'm closing this as a fairly old ticket. While it has merit, at the moment we're pretty much following what JSON Schema does. We may explore that again in the future. |
Issue by quasipedia from Sunday Mar 02, 2014 at 00:16 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/2
While I understand the present specification is an attempt at documenting how swagger works today, I thought the following observations could be of some use at least for discussion / version 1.3.
number
The JSON schema specification says for this primitive:
This possibly means that number should also have the
int32
andint64
formats available (as they are valid), and that eventually the integer type could be killed altogether.date
&date-time
In my opinion these are not formats. A format would be
ISO 8601
(which specifies both date and date-time), for example. Mixingdate
anddate-time
withint32
andint64
is however IMO mixing oranges and apples: the former define the semantics of the string, the latter their boundaries.In general
I believe this section may be a candidate for review: since in JSON the number is encoded as its human-readable representation, there is no need to attach information about the number of bits or the signed/unsigned property.
If the thought was to provide the client with information about the boundaries of the values, this would be better achieved with explicit
maximum
andminimum
fields (and possibly with aresolution
one, telling what is the last significant digit of a result (a far more interesting/useful property to know, in math applications).The text was updated successfully, but these errors were encountered: