allowed placement of x- vendor extensions

421 views
Skip to first unread message

David Biesack

unread,
Jun 18, 2015, 9:59:48 AM6/18/15
to swagger-sw...@googlegroups.com
I know that Swagger 2.0 allows x- vendor extensions in certain locations in the API description,
The spec only documents that these extensions may be used in the Info Object and in Operation Object,

Looking at the Swagger 2.0 JSON schema, x- extension (that is, the patternProperties)
appear to be allowed in many elements:
  • root object
  • tag
  • definitions
  • paths
  • examples
  • operation
  • pathItem
  • responses
  • not
  • bodyParameter
  • headerParameterSubSchema
  • queryParameterSubSchema
  • formDataParameterSubSchema
  • pathParameterSubSchema
  • schema
  • basicAuthenticationSecurity
  • apiKeySecurity
  • oauth2ImplicitSecurity
  • oauth2PasswordSecurity
  • oauth2ApplicationSecurity
  • oauth2AccessCodeSecurity
is this correct, and does this mean the specification is incomplete
or the implementation (schema) oversteps the specification?

Can I add x- extensions to these other elements and still be within the Swagger 2.0 specification?

I realize not all tools will recognize/parse x- extensions, but I mostly want to know if the tools
will ignore them in all these places, or if the tools will fail.

Also, it appears I cannot add extensions to properties in a schema, for example.
I suggest that it would be useful to allow x- vendor extensions in the schema properties (members).
For example, we would like to document (via an extension) which version of an API
a member was added. A schema may be version 4 and I'd like to annotate member x
as added in version 3, for example.

"definitions": {
   "MySchema" : {
              "title" : "....",
               "x-sas-version": "4",
               ....

               "properties" : {
                  "x" : {  "name" : "x",
                           "type" : "string",
                           "x-sas-since" : "3", 
                           ....

thanks,
djb

Ron Ratovsky

unread,
Jun 18, 2015, 10:33:04 AM6/18/15
to swagger-sw...@googlegroups.com
Hi David,

The missing vendor extensions from the spec/schema are due to an oversight and misunderstanding.
There are a few issues opened about it, and I need to update it.
I didn't go over all your list, but if you tell ask me of specific locations where you'd want to include them, I can tell you if it's ok or not. In most cases (if not all) it should be ok.

From the list above, what jumped out is the "not" - that's not a location but rather a JSON Schema directive.

BR,
Ron

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.



--
-----------------------------------------
http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

David Biesack

unread,
Jun 18, 2015, 12:11:33 PM6/18/15
to swagger-sw...@googlegroups.com
Thanks, Ron.

The spec already supports extensions in most the places I think we would like to add them.
The Schema Object and the properties of a Schema Object are probably the only additional places that we would like to use x- extensions.
As I noted in my original post, the JSON schema does not appear to allow 
in the properties of a schema, so we would push that content up to the schema level
(replicating the member map) ... if in fact extensions are supported in the Schema Object.

thanks,
djb


Ron Ratovsky

unread,
Jun 18, 2015, 12:24:21 PM6/18/15
to swagger-sw...@googlegroups.com
Yeah, extensions are supported in the Schema Object. I admit I need to process the inclusion of those in the properties, I'm not sure that would be technically possible since that would eliminate the ability to use property names starting with "x-".
Any chance you can give me an example of how you'd use them directly under the properties?

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

David Biesack

unread,
Jun 18, 2015, 12:42:57 PM6/18/15
to swagger-sw...@googlegroups.com
Sorry, I was unclear - I don't need to put x- extensions inside the properties container,
but only inside individual property values, such as "x-sas-since" below


"definitions": {
   "MySchema" : {
              "title" : "....",
               "x-sas-version": "4",
               ....

               "properties" : {
                  "x" : {  "name" : "x",
                           "type" : "string",
                           "x-sas-since" : "3", 
                           ....
 if this is not allowed, the "roll up" I refer to would be something like
"definitions": {
   "MySchema" : {
              "title" : "....",
               "x-sas-version": "4",
               "x-sas-since" : { "x" : "3",
                                 "y" : "3",
                                 "z" : "4" },

               "properties" : {
                  "x" : {  "name" : "x",
                           "type" : "string",
                        },
                  "y" : {  "name" : "y",
                           "type" : "string",
                        },
                  "z" : {  "name" : "y",
                           "type" : "string",
                        }
                  }
      }
}

Ron Ratovsky

unread,
Jun 18, 2015, 12:47:40 PM6/18/15
to swagger-sw...@googlegroups.com

Oh, there’s no problem there. Each object mapped under properties is a Schema Object on its own, so you can add your extensions directly there.


--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

David Biesack

unread,
Jun 18, 2015, 1:18:09 PM6/18/15
to swagger-sw...@googlegroups.com
cool! thanks
Reply all
Reply to author
Forward
0 new messages