DISCLAIMER
This feature is both EXPERIMENTAL and DISCOURAGED.Third party tooling will simply ignore the x-json-schema property and thus not do any special handling on it's side for you. Paths that include this property will introduce unexpected consequences in third party client generators for instance, where the x-json-schema will not be validated against and thus manual intervention will likely be needed for these paths.
JUSTIFICATION
By default json-schema <http://json-schema.org/> schema's are not supported by the swagger specification (though it does use a sub/superset of the features).This makes swagger incompatible with many recognised standards including json-patch <http://tools.ietf.org/html/rfc6902>.
To ovecome this and allow your specification files to remain 'valid', Mojolicious::Plugin::Swagger2 has added EXPERIMENTAL support for 'x-json-schema' for both input body and response validation. This means that should you choose to adopt one of the many standards that use json-schema and you cannot see a way of converting it to a swagger schema then you may still yield the benefits of request and response validation for those objects as outlined below.
SYNOPSIS
{
"swagger":"2.0",
"basePath":"/api",
"paths":{
"/pets/{name}":{
"patch":{
"operationId":"patchPets",
"parameters":[
{
"name":"name",
"in":"path",
"type":"string"
},
{
"name":"data",
"in":"body",
"schema":{
"type":"object"
},
"x-json-schema":{
"$ref":"http://json.schemastore.org/json-patch"
}
}
],
"responses":{
"226":{
"schema":{
"type":"object"
},
"x-json-schema":{
"$ref":"http://json.schemastore.org/json-patch"
}
}
}
}
}
}
}