allowed placement of x- vendor extensions

[David Biesack]

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,

Paths Object, Path item Object, Parameter Object, Responses Object, Tag Object, Security Scheme 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]

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]

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]

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]

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]

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]

cool! thanks