-
-
-
- swagger
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js b/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js
deleted file mode 100644
index c1c0d4fff2..0000000000
--- a/fixtures/v1.2/helloworld/server/src/main/webapp/lib/backbone-min.js
+++ /dev/null
@@ -1,38 +0,0 @@
-// Backbone.js 0.9.2
-
-// (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc.
-// Backbone may be freely distributed under the MIT license.
-// For all details and documentation:
-// http://backbonejs.org
-(function(){var l=this,y=l.Backbone,z=Array.prototype.slice,A=Array.prototype.splice,g;g="undefined"!==typeof exports?exports:l.Backbone={};g.VERSION="0.9.2";var f=l._;!f&&"undefined"!==typeof require&&(f=require("underscore"));var i=l.jQuery||l.Zepto||l.ender;g.setDomLibrary=function(a){i=a};g.noConflict=function(){l.Backbone=y;return this};g.emulateHTTP=!1;g.emulateJSON=!1;var p=/\s+/,k=g.Events={on:function(a,b,c){var d,e,f,g,j;if(!b)return this;a=a.split(p);for(d=this._callbacks||(this._callbacks=
-{});e=a.shift();)f=(j=d[e])?j.tail:{},f.next=g={},f.context=c,f.callback=b,d[e]={tail:g,next:j?j.next:f};return this},off:function(a,b,c){var d,e,h,g,j,q;if(e=this._callbacks){if(!a&&!b&&!c)return delete this._callbacks,this;for(a=a?a.split(p):f.keys(e);d=a.shift();)if(h=e[d],delete e[d],h&&(b||c))for(g=h.tail;(h=h.next)!==g;)if(j=h.callback,q=h.context,b&&j!==b||c&&q!==c)this.on(d,j,q);return this}},trigger:function(a){var b,c,d,e,f,g;if(!(d=this._callbacks))return this;f=d.all;a=a.split(p);for(g=
-z.call(arguments,1);b=a.shift();){if(c=d[b])for(e=c.tail;(c=c.next)!==e;)c.callback.apply(c.context||this,g);if(c=f){e=c.tail;for(b=[b].concat(g);(c=c.next)!==e;)c.callback.apply(c.context||this,b)}}return this}};k.bind=k.on;k.unbind=k.off;var o=g.Model=function(a,b){var c;a||(a={});b&&b.parse&&(a=this.parse(a));if(c=n(this,"defaults"))a=f.extend({},c,a);b&&b.collection&&(this.collection=b.collection);this.attributes={};this._escapedAttributes={};this.cid=f.uniqueId("c");this.changed={};this._silent=
-{};this._pending={};this.set(a,{silent:!0});this.changed={};this._silent={};this._pending={};this._previousAttributes=f.clone(this.attributes);this.initialize.apply(this,arguments)};f.extend(o.prototype,k,{changed:null,_silent:null,_pending:null,idAttribute:"id",initialize:function(){},toJSON:function(){return f.clone(this.attributes)},get:function(a){return this.attributes[a]},escape:function(a){var b;if(b=this._escapedAttributes[a])return b;b=this.get(a);return this._escapedAttributes[a]=f.escape(null==
-b?"":""+b)},has:function(a){return null!=this.get(a)},set:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c||(c={});if(!d)return this;d instanceof o&&(d=d.attributes);if(c.unset)for(e in d)d[e]=void 0;if(!this._validate(d,c))return!1;this.idAttribute in d&&(this.id=d[this.idAttribute]);var b=c.changes={},h=this.attributes,g=this._escapedAttributes,j=this._previousAttributes||{};for(e in d){a=d[e];if(!f.isEqual(h[e],a)||c.unset&&f.has(h,e))delete g[e],(c.silent?this._silent:
-b)[e]=!0;c.unset?delete h[e]:h[e]=a;!f.isEqual(j[e],a)||f.has(h,e)!=f.has(j,e)?(this.changed[e]=a,c.silent||(this._pending[e]=!0)):(delete this.changed[e],delete this._pending[e])}c.silent||this.change(c);return this},unset:function(a,b){(b||(b={})).unset=!0;return this.set(a,null,b)},clear:function(a){(a||(a={})).unset=!0;return this.set(f.clone(this.attributes),a)},fetch:function(a){var a=a?f.clone(a):{},b=this,c=a.success;a.success=function(d,e,f){if(!b.set(b.parse(d,f),a))return!1;c&&c(b,d)};
-a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},save:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c=c?f.clone(c):{};if(c.wait){if(!this._validate(d,c))return!1;e=f.clone(this.attributes)}a=f.extend({},c,{silent:!0});if(d&&!this.set(d,c.wait?a:c))return!1;var h=this,i=c.success;c.success=function(a,b,e){b=h.parse(a,e);if(c.wait){delete c.wait;b=f.extend(d||{},b)}if(!h.set(b,c))return false;i?i(h,a):h.trigger("sync",h,a,c)};c.error=g.wrapError(c.error,
-h,c);b=this.isNew()?"create":"update";b=(this.sync||g.sync).call(this,b,this,c);c.wait&&this.set(e,a);return b},destroy:function(a){var a=a?f.clone(a):{},b=this,c=a.success,d=function(){b.trigger("destroy",b,b.collection,a)};if(this.isNew())return d(),!1;a.success=function(e){a.wait&&d();c?c(b,e):b.trigger("sync",b,e,a)};a.error=g.wrapError(a.error,b,a);var e=(this.sync||g.sync).call(this,"delete",this,a);a.wait||d();return e},url:function(){var a=n(this,"urlRoot")||n(this.collection,"url")||t();
-return this.isNew()?a:a+("/"==a.charAt(a.length-1)?"":"/")+encodeURIComponent(this.id)},parse:function(a){return a},clone:function(){return new this.constructor(this.attributes)},isNew:function(){return null==this.id},change:function(a){a||(a={});var b=this._changing;this._changing=!0;for(var c in this._silent)this._pending[c]=!0;var d=f.extend({},a.changes,this._silent);this._silent={};for(c in d)this.trigger("change:"+c,this,this.get(c),a);if(b)return this;for(;!f.isEmpty(this._pending);){this._pending=
-{};this.trigger("change",this,a);for(c in this.changed)!this._pending[c]&&!this._silent[c]&&delete this.changed[c];this._previousAttributes=f.clone(this.attributes)}this._changing=!1;return this},hasChanged:function(a){return!arguments.length?!f.isEmpty(this.changed):f.has(this.changed,a)},changedAttributes:function(a){if(!a)return this.hasChanged()?f.clone(this.changed):!1;var b,c=!1,d=this._previousAttributes,e;for(e in a)if(!f.isEqual(d[e],b=a[e]))(c||(c={}))[e]=b;return c},previous:function(a){return!arguments.length||
-!this._previousAttributes?null:this._previousAttributes[a]},previousAttributes:function(){return f.clone(this._previousAttributes)},isValid:function(){return!this.validate(this.attributes)},_validate:function(a,b){if(b.silent||!this.validate)return!0;var a=f.extend({},this.attributes,a),c=this.validate(a,b);if(!c)return!0;b&&b.error?b.error(this,c,b):this.trigger("error",this,c,b);return!1}});var r=g.Collection=function(a,b){b||(b={});b.model&&(this.model=b.model);b.comparator&&(this.comparator=b.comparator);
-this._reset();this.initialize.apply(this,arguments);a&&this.reset(a,{silent:!0,parse:b.parse})};f.extend(r.prototype,k,{model:o,initialize:function(){},toJSON:function(a){return this.map(function(b){return b.toJSON(a)})},add:function(a,b){var c,d,e,g,i,j={},k={},l=[];b||(b={});a=f.isArray(a)?a.slice():[a];c=0;for(d=a.length;c")}return q}function m(r,u,p){var v=h(r,p);var t=a(r);if(t=="no-highlight"){return}var w=t?d(t,v):g(v);t=w.language;var o=c(r);if(o.length){var q=document.createElement("pre");q.innerHTML=w.value;w.value=j(o,c(q),v)}w.value=i(w.value,u,p);var s=r.className;if(!s.match("(\\s|^)(language-)?"+t+"(\\s|$)")){s=s?(s+" "+t):t}r.innerHTML=w.value;r.className=s;r.result={language:t,kw:w.keyword_count,re:w.r};if(w.second_best){r.second_best={language:w.second_best.language,kw:w.second_best.keyword_count,re:w.second_best.r}}}function n(){if(n.called){return}n.called=true;Array.prototype.map.call(document.getElementsByTagName("pre"),b).filter(Boolean).forEach(function(o){m(o,hljs.tabReplace)})}function k(){window.addEventListener("DOMContentLoaded",n,false);window.addEventListener("load",n,false)}var e={};this.LANGUAGES=e;this.highlight=d;this.highlightAuto=g;this.fixMarkup=i;this.highlightBlock=m;this.initHighlighting=n;this.initHighlightingOnLoad=k;this.IR="[a-zA-Z][a-zA-Z0-9_]*";this.UIR="[a-zA-Z_][a-zA-Z0-9_]*";this.NR="\\b\\d+(\\.\\d+)?";this.CNR="(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)";this.BNR="\\b(0b[01]+)";this.RSR="!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|\\.|-|-=|/|/=|:|;|<|<<|<<=|<=|=|==|===|>|>=|>>|>>=|>>>|>>>=|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~";this.BE={b:"\\\\[\\s\\S]",r:0};this.ASM={cN:"string",b:"'",e:"'",i:"\\n",c:[this.BE],r:0};this.QSM={cN:"string",b:'"',e:'"',i:"\\n",c:[this.BE],r:0};this.CLCM={cN:"comment",b:"//",e:"$"};this.CBLCLM={cN:"comment",b:"/\\*",e:"\\*/"};this.HCM={cN:"comment",b:"#",e:"$"};this.NM={cN:"number",b:this.NR,r:0};this.CNM={cN:"number",b:this.CNR,r:0};this.BNM={cN:"number",b:this.BNR,r:0};this.inherit=function(q,r){var o={};for(var p in q){o[p]=q[p]}if(r){for(var p in r){o[p]=r[p]}}return o}}();hljs.LANGUAGES.xml=function(a){var c="[A-Za-z0-9\\._:-]+";var b={eW:true,c:[{cN:"attribute",b:c,r:0},{b:'="',rB:true,e:'"',c:[{cN:"value",b:'"',eW:true}]},{b:"='",rB:true,e:"'",c:[{cN:"value",b:"'",eW:true}]},{b:"=",c:[{cN:"value",b:"[^\\s/>]+"}]}]};return{cI:true,c:[{cN:"pi",b:"<\\?",e:"\\?>",r:10},{cN:"doctype",b:"",r:10,c:[{b:"\\[",e:"\\]"}]},{cN:"comment",b:"",r:10},{cN:"cdata",b:"<\\!\\[CDATA\\[",e:"\\]\\]>",r:10},{cN:"tag",b:"
| t |
","
"]),p.fn.extend({text:function(a){return p.access(this,function(a){return a===b?p.text(this):this.empty().append((this[0]&&this[0].ownerDocument||e).createTextNode(a))},null,a,arguments.length)},wrapAll:function(a){if(p.isFunction(a))return this.each(function(b){p(this).wrapAll(a.call(this,b))});if(this[0]){var b=p(a,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstChild&&a.firstChild.nodeType===1)a=a.firstChild;return a}).append(this)}return this},wrapInner:function(a){return p.isFunction(a)?this.each(function(b){p(this).wrapInner(a.call(this,b))}):this.each(function(){var b=p(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){var b=p.isFunction(a);return this.each(function(c){p(this).wrapAll(b?a.call(this,c):a)})},unwrap:function(){return this.parent().each(function(){p.nodeName(this,"body")||p(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(a){(this.nodeType===1||this.nodeType===11)&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,!0,function(a){(this.nodeType===1||this.nodeType===11)&&this.insertBefore(a,this.firstChild)})},before:function(){if(!bh(this[0]))return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this)});if(arguments.length){var a=p.clean(arguments);return this.pushStack(p.merge(a,this),"before",this.selector)}},after:function(){if(!bh(this[0]))return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this.nextSibling)});if(arguments.length){var a=p.clean(arguments);return this.pushStack(p.merge(this,a),"after",this.selector)}},remove:function(a,b){var c,d=0;for(;(c=this[d])!=null;d++)if(!a||p.filter(a,[c]).length)!b&&c.nodeType===1&&(p.cleanData(c.getElementsByTagName("*")),p.cleanData([c])),c.parentNode&&c.parentNode.removeChild(c);return this},empty:function(){var a,b=0;for(;(a=this[b])!=null;b++){a.nodeType===1&&p.cleanData(a.getElementsByTagName("*"));while(a.firstChild)a.removeChild(a.firstChild)}return this},clone:function(a,b){return a=a==null?!1:a,b=b==null?a:b,this.map(function(){return p.clone(this,a,b)})},html:function(a){return p.access(this,function(a){var c=this[0]||{},d=0,e=this.length;if(a===b)return c.nodeType===1?c.innerHTML.replace(bm,""):b;if(typeof a=="string"&&!bs.test(a)&&(p.support.htmlSerialize||!bu.test(a))&&(p.support.leadingWhitespace||!bn.test(a))&&!bz[(bp.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(bo,"<$1>");try{for(;d| Parameter | \nValue | \nDescription | \nParameter Type | \nData Type | \n
|---|
Error Status Codes
\n| HTTP Status Code | \nReason | \n
|---|
\n \n \n \n
\n ";
- }
-
- buffer += "\n 
\n - \n
- \n \n\n \n
\n \n "; - if (stack1 = helpers.method) { stack1 = stack1.call(depth0, {hash:{},data:data}); } - else { stack1 = depth0.method; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; } - buffer += escapeExpression(stack1) - + "\n \n \n "; - if (stack1 = helpers.path) { stack1 = stack1.call(depth0, {hash:{},data:data}); } - else { stack1 = depth0.path; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; } - buffer += escapeExpression(stack1) - + "\n \n
\n \n \n
\n \n "; - return buffer; - } - -function program9(depth0,data) { - - var buffer = "", stack1; - buffer += "\n "; - stack1 = helpers['if'].call(depth0, depth0.defaultValue, {hash:{},inverse:self.program(12, program12, data),fn:self.program(10, program10, data),data:data}); - if(stack1 || stack1 === 0) { buffer += stack1; } - buffer += "\n "; - return buffer; - } -function program10(depth0,data) { - - var buffer = "", stack1; - buffer += "\n \n "; - return buffer; - } - -function program12(depth0,data) { - - var buffer = "", stack1; - buffer += "\n \n "; - return buffer; - } - - buffer += "
\n \n "; - return buffer; - } - -function program9(depth0,data) { - - var buffer = "", stack1; - buffer += "\n "; - stack1 = helpers['if'].call(depth0, depth0.isFile, {hash:{},inverse:self.program(12, program12, data),fn:self.program(10, program10, data),data:data}); - if(stack1 || stack1 === 0) { buffer += stack1; } - buffer += "\n "; - return buffer; - } -function program10(depth0,data) { - - var buffer = "", stack1; - buffer += "\n \n "; - return buffer; - } - -function program12(depth0,data) { - - var buffer = "", stack1; - buffer += "\n "; - stack1 = helpers['if'].call(depth0, depth0.defaultValue, {hash:{},inverse:self.program(15, program15, data),fn:self.program(13, program13, data),data:data}); - if(stack1 || stack1 === 0) { buffer += stack1; } - buffer += "\n "; - return buffer; - } -function program13(depth0,data) { - - var buffer = "", stack1; - buffer += "\n \n "; - return buffer; - } - -function program15(depth0,data) { - - var buffer = "", stack1; - buffer += "\n \n "; - return buffer; - } - - buffer += "
\n
\n\n";
- return buffer;
- });
-})();
-
-(function() {
- var template = Handlebars.template, templates = Handlebars.templates = Handlebars.templates || {};
-templates['response_content_type'] = template(function (Handlebars,depth0,helpers,partials,data) {
- this.compilerInfo = [4,'>= 1.0.0'];
-helpers = this.merge(helpers, Handlebars.helpers); data = data || {};
- var buffer = "", stack1, functionType="function", self=this;
-
-function program1(depth0,data) {
-
- var buffer = "", stack1;
- buffer += "\n ";
- stack1 = helpers.each.call(depth0, depth0.produces, {hash:{},inverse:self.noop,fn:self.program(2, program2, data),data:data});
- if(stack1 || stack1 === 0) { buffer += stack1; }
- buffer += "\n";
- return buffer;
- }
-function program2(depth0,data) {
-
- var buffer = "", stack1;
- buffer += "\n \n ";
- return buffer;
- }
-
-function program4(depth0,data) {
-
-
- return "\n \n";
- }
-
- buffer += "\n\n";
- return buffer;
- });
-})();
-
-(function() {
- var template = Handlebars.template, templates = Handlebars.templates = Handlebars.templates || {};
-templates['signature'] = template(function (Handlebars,depth0,helpers,partials,data) {
- this.compilerInfo = [4,'>= 1.0.0'];
-helpers = this.merge(helpers, Handlebars.helpers); data = data || {};
- var buffer = "", stack1, functionType="function", escapeExpression=this.escapeExpression;
-
-
- buffer += "\n "; - if (stack1 = helpers.name) { stack1 = stack1.call(depth0, {hash:{},data:data}); } - else { stack1 = depth0.name; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; } - buffer += escapeExpression(stack1) - + " "; - options = {hash:{},inverse:self.noop,fn:self.program(1, program1, data),data:data}; - if (stack1 = helpers.description) { stack1 = stack1.call(depth0, options); } - else { stack1 = depth0.description; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; } - if (!helpers.description) { stack1 = blockHelperMissing.call(depth0, stack1, options); } - if(stack1 || stack1 === 0) { buffer += stack1; } - if (stack1 = helpers.description) { stack1 = stack1.call(depth0, {hash:{},data:data}); } - else { stack1 = depth0.description; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; } - if(stack1 || stack1 === 0) { buffer += stack1; } - buffer += "\n
\n \n\n
- \n
- Model \n
- Model Schema \n
\n\n";
- if (stack1 = helpers.code) { stack1 = stack1.call(depth0, {hash:{},data:data}); }
- else { stack1 = depth0.code; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; }
- buffer += escapeExpression(stack1)
- + " \n";
- if (stack1 = helpers.message) { stack1 = stack1.call(depth0, {hash:{},data:data}); }
- else { stack1 = depth0.message; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; }
- if(stack1 || stack1 === 0) { buffer += stack1; }
- buffer += " \n";
- return buffer;
- });
-})();
-
-
-
-// Generated by CoffeeScript 1.6.3
-(function() {
- var ContentTypeView, HeaderView, MainView, OperationView, ParameterContentTypeView, ParameterView, ResourceView, ResponseContentTypeView, SignatureView, StatusCodeView, SwaggerUi, _ref, _ref1, _ref10, _ref2, _ref3, _ref4, _ref5, _ref6, _ref7, _ref8, _ref9,
- __hasProp = {}.hasOwnProperty,
- __extends = function(child, parent) { for (var key in parent) { if (__hasProp.call(parent, key)) child[key] = parent[key]; } function ctor() { this.constructor = child; } ctor.prototype = parent.prototype; child.prototype = new ctor(); child.__super__ = parent.prototype; return child; };
-
- SwaggerUi = (function(_super) {
- __extends(SwaggerUi, _super);
-
- function SwaggerUi() {
- _ref = SwaggerUi.__super__.constructor.apply(this, arguments);
- return _ref;
- }
-
- SwaggerUi.prototype.dom_id = "swagger_ui";
-
- SwaggerUi.prototype.options = null;
-
- SwaggerUi.prototype.api = null;
-
- SwaggerUi.prototype.headerView = null;
-
- SwaggerUi.prototype.mainView = null;
-
- SwaggerUi.prototype.initialize = function(options) {
- var _this = this;
- if (options == null) {
- options = {};
- }
- if (options.dom_id != null) {
- this.dom_id = options.dom_id;
- delete options.dom_id;
- }
- if ($('#' + this.dom_id) == null) {
- $('body').append('');
- }
- this.options = options;
- this.options.success = function() {
- return _this.render();
- };
- this.options.progress = function(d) {
- return _this.showMessage(d);
- };
- this.options.failure = function(d) {
- return _this.onLoadFailure(d);
- };
- this.headerView = new HeaderView({
- el: $('#header')
- });
- return this.headerView.on('update-swagger-ui', function(data) {
- return _this.updateSwaggerUi(data);
- });
- };
-
- SwaggerUi.prototype.updateSwaggerUi = function(data) {
- this.options.url = data.url;
- return this.load();
- };
-
- SwaggerUi.prototype.load = function() {
- var url, _ref1;
- if ((_ref1 = this.mainView) != null) {
- _ref1.clear();
- }
- url = this.options.url;
- if (url.indexOf("http") !== 0) {
- url = this.buildUrl(window.location.href.toString(), url);
- }
- this.options.url = url;
- this.headerView.update(url);
- this.api = new SwaggerApi(this.options);
- this.api.build();
- return this.api;
- };
-
- SwaggerUi.prototype.render = function() {
- var _this = this;
- this.showMessage('Finished Loading Resource Information. Rendering Swagger UI...');
- this.mainView = new MainView({
- model: this.api,
- el: $('#' + this.dom_id)
- }).render();
- this.showMessage();
- switch (this.options.docExpansion) {
- case "full":
- Docs.expandOperationsForResource('');
- break;
- case "list":
- Docs.collapseOperationsForResource('');
- }
- if (this.options.onComplete) {
- this.options.onComplete(this.api, this);
- }
- return setTimeout(function() {
- return Docs.shebang();
- }, 400);
- };
-
- SwaggerUi.prototype.buildUrl = function(base, url) {
- var endOfPath, parts;
- log("base is " + base);
- if (url.indexOf("/") === 0) {
- parts = base.split("/");
- base = parts[0] + "//" + parts[2];
- return base + url;
- } else {
- endOfPath = base.length;
- if (base.indexOf("?") > -1) {
- endOfPath = Math.min(endOfPath, base.indexOf("?"));
- }
- if (base.indexOf("#") > -1) {
- endOfPath = Math.min(endOfPath, base.indexOf("#"));
- }
- base = base.substring(0, endOfPath);
- if (base.indexOf("/", base.length - 1) !== -1) {
- return base + url;
- }
- return base + "/" + url;
- }
- };
-
- SwaggerUi.prototype.showMessage = function(data) {
- if (data == null) {
- data = '';
- }
- $('#message-bar').removeClass('message-fail');
- $('#message-bar').addClass('message-success');
- return $('#message-bar').html(data);
- };
-
- SwaggerUi.prototype.onLoadFailure = function(data) {
- var val;
- if (data == null) {
- data = '';
- }
- $('#message-bar').removeClass('message-success');
- $('#message-bar').addClass('message-fail');
- val = $('#message-bar').html(data);
- if (this.options.onFailure != null) {
- this.options.onFailure(data);
- }
- return val;
- };
-
- return SwaggerUi;
-
- })(Backbone.Router);
-
- window.SwaggerUi = SwaggerUi;
-
- HeaderView = (function(_super) {
- __extends(HeaderView, _super);
-
- function HeaderView() {
- _ref1 = HeaderView.__super__.constructor.apply(this, arguments);
- return _ref1;
- }
-
- HeaderView.prototype.events = {
- 'click #show-pet-store-icon': 'showPetStore',
- 'click #show-wordnik-dev-icon': 'showWordnikDev',
- 'click #explore': 'showCustom',
- 'keyup #input_baseUrl': 'showCustomOnKeyup',
- 'keyup #input_apiKey': 'showCustomOnKeyup'
- };
-
- HeaderView.prototype.initialize = function() {};
-
- HeaderView.prototype.showPetStore = function(e) {
- return this.trigger('update-swagger-ui', {
- url: "http://petstore.swagger.wordnik.com/api/api-docs"
- });
- };
-
- HeaderView.prototype.showWordnikDev = function(e) {
- return this.trigger('update-swagger-ui', {
- url: "http://api.wordnik.com/v4/resources.json"
- });
- };
-
- HeaderView.prototype.showCustomOnKeyup = function(e) {
- if (e.keyCode === 13) {
- return this.showCustom();
- }
- };
-
- HeaderView.prototype.showCustom = function(e) {
- if (e != null) {
- e.preventDefault();
- }
- return this.trigger('update-swagger-ui', {
- url: $('#input_baseUrl').val(),
- apiKey: $('#input_apiKey').val()
- });
- };
-
- HeaderView.prototype.update = function(url, apiKey, trigger) {
- if (trigger == null) {
- trigger = false;
- }
- $('#input_baseUrl').val(url);
- if (trigger) {
- return this.trigger('update-swagger-ui', {
- url: url
- });
- }
- };
-
- return HeaderView;
-
- })(Backbone.View);
-
- MainView = (function(_super) {
- __extends(MainView, _super);
-
- function MainView() {
- _ref2 = MainView.__super__.constructor.apply(this, arguments);
- return _ref2;
- }
-
- MainView.prototype.initialize = function() {};
-
- MainView.prototype.render = function() {
- var counter, id, resource, resources, _i, _len, _ref3;
- $(this.el).html(Handlebars.templates.main(this.model));
- resources = {};
- counter = 0;
- _ref3 = this.model.apisArray;
- for (_i = 0, _len = _ref3.length; _i < _len; _i++) {
- resource = _ref3[_i];
- id = resource.name;
- while (typeof resources[id] !== 'undefined') {
- id = id + "_" + counter;
- counter += 1;
- }
- resource.id = id;
- resources[id] = resource;
- this.addResource(resource);
- }
- return this;
- };
-
- MainView.prototype.addResource = function(resource) {
- var resourceView;
- resourceView = new ResourceView({
- model: resource,
- tagName: 'li',
- id: 'resource_' + resource.id,
- className: 'resource'
- });
- return $('#resources').append(resourceView.render().el);
- };
-
- MainView.prototype.clear = function() {
- return $(this.el).html('');
- };
-
- return MainView;
-
- })(Backbone.View);
-
- ResourceView = (function(_super) {
- __extends(ResourceView, _super);
-
- function ResourceView() {
- _ref3 = ResourceView.__super__.constructor.apply(this, arguments);
- return _ref3;
- }
-
- ResourceView.prototype.initialize = function() {};
-
- ResourceView.prototype.render = function() {
- var counter, id, methods, operation, _i, _len, _ref4;
- $(this.el).html(Handlebars.templates.resource(this.model));
- methods = {};
- _ref4 = this.model.operationsArray;
- for (_i = 0, _len = _ref4.length; _i < _len; _i++) {
- operation = _ref4[_i];
- counter = 0;
- id = operation.nickname;
- while (typeof methods[id] !== 'undefined') {
- id = id + "_" + counter;
- counter += 1;
- }
- methods[id] = operation;
- operation.nickname = id;
- operation.parentId = this.model.id;
- this.addOperation(operation);
- }
- return this;
- };
-
- ResourceView.prototype.addOperation = function(operation) {
- var operationView;
- operation.number = this.number;
- operationView = new OperationView({
- model: operation,
- tagName: 'li',
- className: 'endpoint'
- });
- $('.endpoints', $(this.el)).append(operationView.render().el);
- return this.number++;
- };
-
- return ResourceView;
-
- })(Backbone.View);
-
- OperationView = (function(_super) {
- __extends(OperationView, _super);
-
- function OperationView() {
- _ref4 = OperationView.__super__.constructor.apply(this, arguments);
- return _ref4;
- }
-
- OperationView.prototype.invocationUrl = null;
-
- OperationView.prototype.events = {
- 'submit .sandbox': 'submitOperation',
- 'click .submit': 'submitOperation',
- 'click .response_hider': 'hideResponse',
- 'click .toggleOperation': 'toggleOperationContent'
- };
-
- OperationView.prototype.initialize = function() {};
-
- OperationView.prototype.render = function() {
- var contentTypeModel, isMethodSubmissionSupported, param, responseContentTypeView, responseSignatureView, signatureModel, statusCode, type, _i, _j, _k, _len, _len1, _len2, _ref5, _ref6, _ref7;
- isMethodSubmissionSupported = true;
- if (!isMethodSubmissionSupported) {
- this.model.isReadOnly = true;
- }
- $(this.el).html(Handlebars.templates.operation(this.model));
- if (this.model.responseClassSignature && this.model.responseClassSignature !== 'string') {
- signatureModel = {
- sampleJSON: this.model.responseSampleJSON,
- isParam: false,
- signature: this.model.responseClassSignature
- };
- responseSignatureView = new SignatureView({
- model: signatureModel,
- tagName: 'div'
- });
- $('.model-signature', $(this.el)).append(responseSignatureView.render().el);
- } else {
- $('.model-signature', $(this.el)).html(this.model.type);
- }
- contentTypeModel = {
- isParam: false
- };
- contentTypeModel.consumes = this.model.consumes;
- contentTypeModel.produces = this.model.produces;
- _ref5 = this.model.parameters;
- for (_i = 0, _len = _ref5.length; _i < _len; _i++) {
- param = _ref5[_i];
- type = param.type || param.dataType;
- if (type.toLowerCase() === 'file') {
- if (!contentTypeModel.consumes) {
- log("set content type ");
- contentTypeModel.consumes = 'multipart/form-data';
- }
- }
- }
- responseContentTypeView = new ResponseContentTypeView({
- model: contentTypeModel
- });
- $('.response-content-type', $(this.el)).append(responseContentTypeView.render().el);
- _ref6 = this.model.parameters;
- for (_j = 0, _len1 = _ref6.length; _j < _len1; _j++) {
- param = _ref6[_j];
- this.addParameter(param, contentTypeModel.consumes);
- }
- _ref7 = this.model.responseMessages;
- for (_k = 0, _len2 = _ref7.length; _k < _len2; _k++) {
- statusCode = _ref7[_k];
- this.addStatusCode(statusCode);
- }
- return this;
- };
-
- OperationView.prototype.addParameter = function(param, consumes) {
- var paramView;
- param.consumes = consumes;
- paramView = new ParameterView({
- model: param,
- tagName: 'tr',
- readOnly: this.model.isReadOnly
- });
- return $('.operation-params', $(this.el)).append(paramView.render().el);
- };
-
- OperationView.prototype.addStatusCode = function(statusCode) {
- var statusCodeView;
- statusCodeView = new StatusCodeView({
- model: statusCode,
- tagName: 'tr'
- });
- return $('.operation-status', $(this.el)).append(statusCodeView.render().el);
- };
-
- OperationView.prototype.submitOperation = function(e) {
- var error_free, form, isFileUpload, map, o, opts, val, _i, _j, _k, _len, _len1, _len2, _ref5, _ref6, _ref7;
- if (e != null) {
- e.preventDefault();
- }
- form = $('.sandbox', $(this.el));
- error_free = true;
- form.find("input.required").each(function() {
- var _this = this;
- $(this).removeClass("error");
- if (jQuery.trim($(this).val()) === "") {
- $(this).addClass("error");
- $(this).wiggle({
- callback: function() {
- return $(_this).focus();
- }
- });
- return error_free = false;
- }
- });
- if (error_free) {
- map = {};
- opts = {
- parent: this
- };
- isFileUpload = false;
- _ref5 = form.find("input");
- for (_i = 0, _len = _ref5.length; _i < _len; _i++) {
- o = _ref5[_i];
- if ((o.value != null) && jQuery.trim(o.value).length > 0) {
- map[o.name] = o.value;
- }
- if (o.type === "file") {
- isFileUpload = true;
- }
- }
- _ref6 = form.find("textarea");
- for (_j = 0, _len1 = _ref6.length; _j < _len1; _j++) {
- o = _ref6[_j];
- if ((o.value != null) && jQuery.trim(o.value).length > 0) {
- map["body"] = o.value;
- }
- }
- _ref7 = form.find("select");
- for (_k = 0, _len2 = _ref7.length; _k < _len2; _k++) {
- o = _ref7[_k];
- val = this.getSelectedValue(o);
- if ((val != null) && jQuery.trim(val).length > 0) {
- map[o.name] = val;
- }
- }
- opts.responseContentType = $("div select[name=responseContentType]", $(this.el)).val();
- opts.requestContentType = $("div select[name=parameterContentType]", $(this.el)).val();
- $(".response_throbber", $(this.el)).show();
- if (isFileUpload) {
- return this.handleFileUpload(map, form);
- } else {
- return this.model["do"](map, opts, this.showCompleteStatus, this.showErrorStatus, this);
- }
- }
- };
-
- OperationView.prototype.success = function(response, parent) {
- return parent.showCompleteStatus(response);
- };
-
- OperationView.prototype.handleFileUpload = function(map, form) {
- var bodyParam, el, headerParams, o, obj, param, _i, _j, _k, _l, _len, _len1, _len2, _len3, _ref5, _ref6, _ref7, _ref8,
- _this = this;
- log("it's a file upload");
- _ref5 = form.serializeArray();
- for (_i = 0, _len = _ref5.length; _i < _len; _i++) {
- o = _ref5[_i];
- if ((o.value != null) && jQuery.trim(o.value).length > 0) {
- map[o.name] = o.value;
- }
- }
- bodyParam = new FormData();
- _ref6 = this.model.parameters;
- for (_j = 0, _len1 = _ref6.length; _j < _len1; _j++) {
- param = _ref6[_j];
- if (param.paramType === 'form') {
- bodyParam.append(param.name, map[param.name]);
- }
- }
- headerParams = {};
- _ref7 = this.model.parameters;
- for (_k = 0, _len2 = _ref7.length; _k < _len2; _k++) {
- param = _ref7[_k];
- if (param.paramType === 'header') {
- headerParams[param.name] = map[param.name];
- }
- }
- log(headerParams);
- _ref8 = form.find('input[type~="file"]');
- for (_l = 0, _len3 = _ref8.length; _l < _len3; _l++) {
- el = _ref8[_l];
- bodyParam.append($(el).attr('name'), el.files[0]);
- }
- log(bodyParam);
- this.invocationUrl = this.model.supportHeaderParams() ? (headerParams = this.model.getHeaderParams(map), this.model.urlify(map, false)) : this.model.urlify(map, true);
- $(".request_url", $(this.el)).html("
"); - return $(".response_body", $(this.el)).html(escape(prettyJson)); - }; - - OperationView.prototype.showErrorStatus = function(data, parent) { - return parent.showStatus(data); - }; - - OperationView.prototype.showCompleteStatus = function(data, parent) { - return parent.showStatus(data); - }; - - OperationView.prototype.formatXml = function(xml) { - var contexp, formatted, indent, lastType, lines, ln, pad, reg, transitions, wsexp, _fn, _i, _len; - reg = /(>)(<)(\/*)/g; - wsexp = /[ ]*(.*)[ ]+\n/g; - contexp = /(<.+>)(.+\n)/g; - xml = xml.replace(reg, '$1\n$2$3').replace(wsexp, '$1\n').replace(contexp, '$1\n$2'); - pad = 0; - formatted = ''; - lines = xml.split('\n'); - indent = 0; - lastType = 'other'; - transitions = { - 'single->single': 0, - 'single->closing': -1, - 'single->opening': 0, - 'single->other': 0, - 'closing->single': 0, - 'closing->closing': -1, - 'closing->opening': 0, - 'closing->other': 0, - 'opening->single': 1, - 'opening->closing': 0, - 'opening->opening': 1, - 'opening->other': 1, - 'other->single': 0, - 'other->closing': -1, - 'other->opening': 0, - 'other->other': 0 - }; - _fn = function(ln) { - var fromTo, j, key, padding, type, types, value; - types = { - single: Boolean(ln.match(/<.+\/>/)), - closing: Boolean(ln.match(/<\/.+>/)), - opening: Boolean(ln.match(/<[^!?].*>/)) - }; - type = ((function() { - var _results; - _results = []; - for (key in types) { - value = types[key]; - if (value) { - _results.push(key); - } - } - return _results; - })())[0]; - type = type === void 0 ? 'other' : type; - fromTo = lastType + '->' + type; - lastType = type; - padding = ''; - indent += transitions[fromTo]; - padding = ((function() { - var _j, _ref5, _results; - _results = []; - for (j = _j = 0, _ref5 = indent; 0 <= _ref5 ? _j < _ref5 : _j > _ref5; j = 0 <= _ref5 ? ++_j : --_j) { - _results.push(' '); - } - return _results; - })()).join(''); - if (fromTo === 'opening->closing') { - return formatted = formatted.substr(0, formatted.length - 1) + ln + '\n'; - } else { - return formatted += padding + ln + '\n'; - } - }; - for (_i = 0, _len = lines.length; _i < _len; _i++) { - ln = lines[_i]; - _fn(ln); - } - return formatted; - }; - - OperationView.prototype.showStatus = function(response) { - var code, content, contentType, headers, pre, response_body, url; - if (response.content === void 0) { - content = response.data; - url = response.url; - } else { - content = response.content.data; - url = response.request.url; - } - headers = response.headers; - contentType = headers && headers["Content-Type"] ? headers["Content-Type"].split(";")[0].trim() : null; - if (!content) { - code = $('![]()
').attr('src', url);
- } else {
- code = $('
\n \n '}function q(t,s){return'\n\n \n
\n '}function p(t,s){return"\n \n \n \n
\n "}function o(t,s){return"\n "}function e(t,s){return"\n
\n \n ';return u}function e(x,w){var u="",v;u+="\n ";v=o["if"].call(x,x.defaultValue,{hash:{},inverse:n.program(12,r,w),fn:n.program(10,t,w),data:w});if(v||v===0){u+=v}u+="\n ";return u}function t(x,w){var u="",v;u+="\n \n ";return u}function r(x,w){var u="",v;u+="\n \n ";return u}p+="";if(g=o.name){g=g.call(q,{hash:{},data:s})}else{g=q.name;g=typeof g===d?g.apply(q):g}p+=c(g)+" \n\n\n ";g=o["if"].call(q,q.isBody,{hash:{},inverse:n.program(9,e,s),fn:n.program(1,m,s),data:s});if(g||g===0){p+=g}p+="\n\n \n";if(g=o.description){g=g.call(q,{hash:{},data:s})}else{g=q.description;g=typeof g===d?g.apply(q):g}if(g||g===0){p+=g}p+=" \n";if(g=o.paramType){g=g.call(q,{hash:{},data:s})}else{g=q.paramType;g=typeof g===d?g.apply(q):g}if(g||g===0){p+=g}p+=' \n\n \n \n';return p})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.param_list=b(function(h,t,r,m,y){this.compilerInfo=[4,">= 1.0.0"];r=this.merge(r,h.helpers);y=y||{};var s="",j,g,e,p=this,q=r.helperMissing,d="function",c=this.escapeExpression;function o(A,z){return" multiple='multiple'"}function n(A,z){return"\n "}function l(C,B){var z="",A;z+="\n ";A=r["if"].call(C,C.defaultValue,{hash:{},inverse:p.program(8,i,B),fn:p.program(6,k,B),data:B});if(A||A===0){z+=A}z+="\n ";return z}function k(A,z){return"\n "}function i(E,D){var z="",C,B,A;z+="\n ";A={hash:{},inverse:p.program(11,x,D),fn:p.program(9,f,D),data:D};B=((C=r.isArray||E.isArray),C?C.call(E,E,A):q.call(E,"isArray",E,A));if(B||B===0){z+=B}z+="\n ";return z}function f(A,z){return"\n "}function x(A,z){return"\n \n "}function w(C,B){var z="",A;z+="\n ";A=r["if"].call(C,C.isDefault,{hash:{},inverse:p.program(16,u,B),fn:p.program(14,v,B),data:B});if(A||A===0){z+=A}z+="\n ";return z}function v(C,B){var z="",A;z+='\n \n ";return z}function u(C,B){var z="",A;z+="\n \n ";return z}s+="";if(j=r.name){j=j.call(t,{hash:{},data:y})}else{j=t.name;j=typeof j===d?j.apply(t):j}s+=c(j)+" \n\n \n \n";if(g=r.description){g=g.call(t,{hash:{},data:y})}else{g=t.description;g=typeof g===d?g.apply(t):g}if(g||g===0){s+=g}s+=" \n";if(g=r.paramType){g=g.call(t,{hash:{},data:y})}else{g=t.paramType;g=typeof g===d?g.apply(t):g}if(g||g===0){s+=g}s+=' \n";if(d=f.name){d=d.call(m,{hash:{},data:k})}else{d=m.name;d=typeof d===h?d.apply(m):d}i+=j(d)+" \n\n ";d=f["if"].call(m,m.isBody,{hash:{},inverse:o.program(3,c,k),fn:o.program(1,e,k),data:k});if(d||d===0){i+=d}i+="\n \n";if(d=f.description){d=d.call(m,{hash:{},data:k})}else{d=m.description;d=typeof d===h?d.apply(m):d}if(d||d===0){i+=d}i+=" \n";if(d=f.paramType){d=d.call(m,{hash:{},data:k})}else{d=m.paramType;d=typeof d===h?d.apply(m):d}if(d||d===0){i+=d}i+=' \n";if(d=f.name){d=d.call(m,{hash:{},data:k})}else{d=m.name;d=typeof d===h?d.apply(m):d}i+=j(d)+" \n\n ";d=f["if"].call(m,m.isBody,{hash:{},inverse:o.program(3,c,k),fn:o.program(1,e,k),data:k});if(d||d===0){i+=d}i+="\n \n";if(d=f.description){d=d.call(m,{hash:{},data:k})}else{d=m.description;d=typeof d===h?d.apply(m):d}if(d||d===0){i+=d}i+=" \n";if(d=f.paramType){d=d.call(m,{hash:{},data:k})}else{d=m.paramType;d=typeof d===h?d.apply(m):d}if(d||d===0){i+=d}i+=' \n
\n \n ';return w}function e(z,y){var w="",x;w+="\n ";x=o["if"].call(z,z.isFile,{hash:{},inverse:n.program(12,t,y),fn:n.program(10,v,y),data:y});if(x||x===0){w+=x}w+="\n ";return w}function v(z,y){var w="",x;w+="\n \n ";return w}function t(z,y){var w="",x;w+="\n ";x=o["if"].call(z,z.defaultValue,{hash:{},inverse:n.program(15,r,y),fn:n.program(13,s,y),data:y});if(x||x===0){w+=x}w+="\n ";return w}function s(z,y){var w="",x;w+="\n \n ";return w}function r(z,y){var w="",x;w+="\n \n ";return w}p+="";if(g=o.name){g=g.call(q,{hash:{},data:u})}else{g=q.name;g=typeof g===d?g.apply(q):g}p+=c(g)+" \n\n ";g=o["if"].call(q,q.isBody,{hash:{},inverse:n.program(9,e,u),fn:n.program(1,m,u),data:u});if(g||g===0){p+=g}p+="\n \n\n ";if(g=o.description){g=g.call(q,{hash:{},data:u})}else{g=q.description;g=typeof g===d?g.apply(q):g}if(g||g===0){p+=g}p+="\n \n";if(g=o.paramType){g=g.call(q,{hash:{},data:u})}else{g=q.paramType;g=typeof g===d?g.apply(q):g}if(g||g===0){p+=g}p+=' \n
\n
\n\n";
- return buffer;
- });
-})();
-
-(function() {
- var template = Handlebars.template, templates = Handlebars.templates = Handlebars.templates || {};
-templates['status_code'] = template(function (Handlebars,depth0,helpers,partials,data) {
- this.compilerInfo = [4,'>= 1.0.0'];
-helpers = this.merge(helpers, Handlebars.helpers); data = data || {};
- var buffer = "", stack1, functionType="function", escapeExpression=this.escapeExpression;
-
-
- buffer += "\n ";
- if (stack1 = helpers.signature) { stack1 = stack1.call(depth0, {hash:{},data:data}); }
- else { stack1 = depth0.signature; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; }
- if(stack1 || stack1 === 0) { buffer += stack1; }
- buffer += "\n
\n\n \n
\n";
- if (stack1 = helpers.sampleJSON) { stack1 = stack1.call(depth0, {hash:{},data:data}); }
- else { stack1 = depth0.sampleJSON; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; }
- buffer += escapeExpression(stack1)
- + "" + this.invocationUrl + ""); - obj = { - type: this.model.method, - url: this.invocationUrl, - headers: headerParams, - data: bodyParam, - dataType: 'json', - contentType: false, - processData: false, - error: function(data, textStatus, error) { - return _this.showErrorStatus(_this.wrap(data), _this); - }, - success: function(data) { - return _this.showResponse(data, _this); - }, - complete: function(data) { - return _this.showCompleteStatus(_this.wrap(data), _this); - } - }; - if (window.authorizations) { - window.authorizations.apply(obj); - } - jQuery.ajax(obj); - return false; - }; - - OperationView.prototype.wrap = function(data) { - var headerArray, headers, i, o, _i, _ref5, _ref6; - headers = {}; - headerArray = data.getAllResponseHeaders().split(":"); - for (i = _i = 0, _ref5 = headerArray.length / 2, _ref6 = 2.; _ref6 > 0 ? _i <= _ref5 : _i >= _ref5; i = _i += _ref6) { - headers[headerArray[i]] = headerArray[i + 1]; - } - o = {}; - o.content = {}; - o.content.data = data.responseText; - o.headers = headers; - o.request = {}; - o.request.url = this.invocationUrl; - o.status = data.status; - return o; - }; - - OperationView.prototype.getSelectedValue = function(select) { - var opt, options, _i, _len, _ref5; - if (!select.multiple) { - return select.value; - } else { - options = []; - _ref5 = select.options; - for (_i = 0, _len = _ref5.length; _i < _len; _i++) { - opt = _ref5[_i]; - if (opt.selected) { - options.push(opt.value); - } - } - if (options.length > 0) { - return options.join(","); - } else { - return null; - } - } - }; - - OperationView.prototype.hideResponse = function(e) { - if (e != null) { - e.preventDefault(); - } - $(".response", $(this.el)).slideUp(); - return $(".response_hider", $(this.el)).fadeOut(); - }; - - OperationView.prototype.showResponse = function(response) { - var prettyJson; - prettyJson = JSON.stringify(response, null, "\t").replace(/\n/g, "
"); - return $(".response_body", $(this.el)).html(escape(prettyJson)); - }; - - OperationView.prototype.showErrorStatus = function(data, parent) { - return parent.showStatus(data); - }; - - OperationView.prototype.showCompleteStatus = function(data, parent) { - return parent.showStatus(data); - }; - - OperationView.prototype.formatXml = function(xml) { - var contexp, formatted, indent, lastType, lines, ln, pad, reg, transitions, wsexp, _fn, _i, _len; - reg = /(>)(<)(\/*)/g; - wsexp = /[ ]*(.*)[ ]+\n/g; - contexp = /(<.+>)(.+\n)/g; - xml = xml.replace(reg, '$1\n$2$3').replace(wsexp, '$1\n').replace(contexp, '$1\n$2'); - pad = 0; - formatted = ''; - lines = xml.split('\n'); - indent = 0; - lastType = 'other'; - transitions = { - 'single->single': 0, - 'single->closing': -1, - 'single->opening': 0, - 'single->other': 0, - 'closing->single': 0, - 'closing->closing': -1, - 'closing->opening': 0, - 'closing->other': 0, - 'opening->single': 1, - 'opening->closing': 0, - 'opening->opening': 1, - 'opening->other': 1, - 'other->single': 0, - 'other->closing': -1, - 'other->opening': 0, - 'other->other': 0 - }; - _fn = function(ln) { - var fromTo, j, key, padding, type, types, value; - types = { - single: Boolean(ln.match(/<.+\/>/)), - closing: Boolean(ln.match(/<\/.+>/)), - opening: Boolean(ln.match(/<[^!?].*>/)) - }; - type = ((function() { - var _results; - _results = []; - for (key in types) { - value = types[key]; - if (value) { - _results.push(key); - } - } - return _results; - })())[0]; - type = type === void 0 ? 'other' : type; - fromTo = lastType + '->' + type; - lastType = type; - padding = ''; - indent += transitions[fromTo]; - padding = ((function() { - var _j, _ref5, _results; - _results = []; - for (j = _j = 0, _ref5 = indent; 0 <= _ref5 ? _j < _ref5 : _j > _ref5; j = 0 <= _ref5 ? ++_j : --_j) { - _results.push(' '); - } - return _results; - })()).join(''); - if (fromTo === 'opening->closing') { - return formatted = formatted.substr(0, formatted.length - 1) + ln + '\n'; - } else { - return formatted += padding + ln + '\n'; - } - }; - for (_i = 0, _len = lines.length; _i < _len; _i++) { - ln = lines[_i]; - _fn(ln); - } - return formatted; - }; - - OperationView.prototype.showStatus = function(response) { - var code, content, contentType, headers, pre, response_body, url; - if (response.content === void 0) { - content = response.data; - url = response.url; - } else { - content = response.content.data; - url = response.request.url; - } - headers = response.headers; - contentType = headers && headers["Content-Type"] ? headers["Content-Type"].split(";")[0].trim() : null; - if (!content) { - code = $('
" + url + ""); - $(".response_code", $(this.el)).html("
" + response.status + ""); - $(".response_body", $(this.el)).html(response_body); - $(".response_headers", $(this.el)).html("
" + JSON.stringify(response.headers, null, " ").replace(/\n/g, ""); - $(".response", $(this.el)).slideDown(); - $(".response_hider", $(this.el)).show(); - $(".response_throbber", $(this.el)).hide(); - return hljs.highlightBlock($('.response_body', $(this.el))[0]); - }; - - OperationView.prototype.toggleOperationContent = function() { - var elem; - elem = $('#' + Docs.escapeResourceName(this.model.parentId) + "_" + this.model.nickname + "_content"); - if (elem.is(':visible')) { - return Docs.collapseOperation(elem); - } else { - return Docs.expandOperation(elem); - } - }; - - return OperationView; - - })(Backbone.View); - - StatusCodeView = (function(_super) { - __extends(StatusCodeView, _super); - - function StatusCodeView() { - _ref5 = StatusCodeView.__super__.constructor.apply(this, arguments); - return _ref5; - } - - StatusCodeView.prototype.initialize = function() {}; - - StatusCodeView.prototype.render = function() { - var template; - template = this.template(); - $(this.el).html(template(this.model)); - return this; - }; - - StatusCodeView.prototype.template = function() { - return Handlebars.templates.status_code; - }; - - return StatusCodeView; - - })(Backbone.View); - - ParameterView = (function(_super) { - __extends(ParameterView, _super); - - function ParameterView() { - _ref6 = ParameterView.__super__.constructor.apply(this, arguments); - return _ref6; - } - - ParameterView.prototype.initialize = function() { - return Handlebars.registerHelper('isArray', function(param, opts) { - if (param.type.toLowerCase() === 'array' || param.allowMultiple) { - return opts.fn(this); - } else { - return opts.inverse(this); - } - }); - }; - - ParameterView.prototype.render = function() { - var contentTypeModel, isParam, parameterContentTypeView, responseContentTypeView, signatureModel, signatureView, template, type; - type = this.model.type || this.model.dataType; - if (this.model.paramType === 'body') { - this.model.isBody = true; - } - if (type.toLowerCase() === 'file') { - this.model.isFile = true; - } - template = this.template(); - $(this.el).html(template(this.model)); - signatureModel = { - sampleJSON: this.model.sampleJSON, - isParam: true, - signature: this.model.signature - }; - if (this.model.sampleJSON) { - signatureView = new SignatureView({ - model: signatureModel, - tagName: 'div' - }); - $('.model-signature', $(this.el)).append(signatureView.render().el); - } else { - $('.model-signature', $(this.el)).html(this.model.signature); - } - isParam = false; - if (this.model.isBody) { - isParam = true; - } - contentTypeModel = { - isParam: isParam - }; - contentTypeModel.consumes = this.model.consumes; - if (isParam) { - parameterContentTypeView = new ParameterContentTypeView({ - model: contentTypeModel - }); - $('.parameter-content-type', $(this.el)).append(parameterContentTypeView.render().el); - } else { - responseContentTypeView = new ResponseContentTypeView({ - model: contentTypeModel - }); - $('.response-content-type', $(this.el)).append(responseContentTypeView.render().el); - } - return this; - }; - - ParameterView.prototype.template = function() { - if (this.model.isList) { - return Handlebars.templates.param_list; - } else { - if (this.options.readOnly) { - if (this.model.required) { - return Handlebars.templates.param_readonly_required; - } else { - return Handlebars.templates.param_readonly; - } - } else { - if (this.model.required) { - return Handlebars.templates.param_required; - } else { - return Handlebars.templates.param; - } - } - } - }; - - return ParameterView; - - })(Backbone.View); - - SignatureView = (function(_super) { - __extends(SignatureView, _super); - - function SignatureView() { - _ref7 = SignatureView.__super__.constructor.apply(this, arguments); - return _ref7; - } - - SignatureView.prototype.events = { - 'click a.description-link': 'switchToDescription', - 'click a.snippet-link': 'switchToSnippet', - 'mousedown .snippet': 'snippetToTextArea' - }; - - SignatureView.prototype.initialize = function() {}; - - SignatureView.prototype.render = function() { - var template; - template = this.template(); - $(this.el).html(template(this.model)); - this.switchToDescription(); - this.isParam = this.model.isParam; - if (this.isParam) { - $('.notice', $(this.el)).text('Click to set as parameter value'); - } - return this; - }; - - SignatureView.prototype.template = function() { - return Handlebars.templates.signature; - }; - - SignatureView.prototype.switchToDescription = function(e) { - if (e != null) { - e.preventDefault(); - } - $(".snippet", $(this.el)).hide(); - $(".description", $(this.el)).show(); - $('.description-link', $(this.el)).addClass('selected'); - return $('.snippet-link', $(this.el)).removeClass('selected'); - }; - - SignatureView.prototype.switchToSnippet = function(e) { - if (e != null) { - e.preventDefault(); - } - $(".description", $(this.el)).hide(); - $(".snippet", $(this.el)).show(); - $('.snippet-link', $(this.el)).addClass('selected'); - return $('.description-link', $(this.el)).removeClass('selected'); - }; - - SignatureView.prototype.snippetToTextArea = function(e) { - var textArea; - if (this.isParam) { - if (e != null) { - e.preventDefault(); - } - textArea = $('textarea', $(this.el.parentNode.parentNode.parentNode)); - if ($.trim(textArea.val()) === '') { - return textArea.val(this.model.sampleJSON); - } - } - }; - - return SignatureView; - - })(Backbone.View); - - ContentTypeView = (function(_super) { - __extends(ContentTypeView, _super); - - function ContentTypeView() { - _ref8 = ContentTypeView.__super__.constructor.apply(this, arguments); - return _ref8; - } - - ContentTypeView.prototype.initialize = function() {}; - - ContentTypeView.prototype.render = function() { - var template; - template = this.template(); - $(this.el).html(template(this.model)); - $('label[for=contentType]', $(this.el)).text('Response Content Type'); - return this; - }; - - ContentTypeView.prototype.template = function() { - return Handlebars.templates.content_type; - }; - - return ContentTypeView; - - })(Backbone.View); - - ResponseContentTypeView = (function(_super) { - __extends(ResponseContentTypeView, _super); - - function ResponseContentTypeView() { - _ref9 = ResponseContentTypeView.__super__.constructor.apply(this, arguments); - return _ref9; - } - - ResponseContentTypeView.prototype.initialize = function() {}; - - ResponseContentTypeView.prototype.render = function() { - var template; - template = this.template(); - $(this.el).html(template(this.model)); - $('label[for=responseContentType]', $(this.el)).text('Response Content Type'); - return this; - }; - - ResponseContentTypeView.prototype.template = function() { - return Handlebars.templates.response_content_type; - }; - - return ResponseContentTypeView; - - })(Backbone.View); - - ParameterContentTypeView = (function(_super) { - __extends(ParameterContentTypeView, _super); - - function ParameterContentTypeView() { - _ref10 = ParameterContentTypeView.__super__.constructor.apply(this, arguments); - return _ref10; - } - - ParameterContentTypeView.prototype.initialize = function() {}; - - ParameterContentTypeView.prototype.render = function() { - var template; - template = this.template(); - $(this.el).html(template(this.model)); - $('label[for=parameterContentType]', $(this.el)).text('Parameter content type:'); - return this; - }; - - ParameterContentTypeView.prototype.template = function() { - return Handlebars.templates.parameter_content_type; - }; - - return ParameterContentTypeView; - - })(Backbone.View); - -}).call(this); diff --git a/fixtures/v1.2/helloworld/server/src/main/webapp/swagger-ui.min.js b/fixtures/v1.2/helloworld/server/src/main/webapp/swagger-ui.min.js deleted file mode 100644 index 10bf6ace6e..0000000000 --- a/fixtures/v1.2/helloworld/server/src/main/webapp/swagger-ui.min.js +++ /dev/null @@ -1 +0,0 @@ -$(function(){$.fn.vAlign=function(){return this.each(function(c){var a=$(this).height();var d=$(this).parent().height();var b=(d-a)/2;$(this).css("margin-top",b)})};$.fn.stretchFormtasticInputWidthToParent=function(){return this.each(function(b){var d=$(this).closest("form").innerWidth();var c=parseInt($(this).closest("form").css("padding-left"),10)+parseInt($(this).closest("form").css("padding-right"),10);var a=parseInt($(this).css("padding-left"),10)+parseInt($(this).css("padding-right"),10);$(this).css("width",d-c-a)})};$("form.formtastic li.string input, form.formtastic textarea").stretchFormtasticInputWidthToParent();$("ul.downplayed li div.content p").vAlign();$("form.sandbox").submit(function(){var a=true;$(this).find("input.required").each(function(){$(this).removeClass("error");if($(this).val()==""){$(this).addClass("error");$(this).wiggle();a=false}});return a})});function clippyCopiedCallback(b){$("#api_key_copied").fadeIn().delay(1000).fadeOut()}log=function(){log.history=log.history||[];log.history.push(arguments);if(this.console){console.log(Array.prototype.slice.call(arguments))}};if(Function.prototype.bind&&console&&typeof console.log=="object"){["log","info","warn","error","assert","dir","clear","profile","profileEnd"].forEach(function(a){console[a]=this.bind(console[a],console)},Function.prototype.call)}var Docs={shebang:function(){var b=$.param.fragment().split("/");b.shift();switch(b.length){case 1:log("shebang resource:"+b[0]);var d="resource_"+b[0];Docs.expandEndpointListForResource(b[0]);$("#"+d).slideto({highlight:false});break;case 2:log("shebang endpoint: "+b.join("_"));Docs.expandEndpointListForResource(b[0]);$("#"+d).slideto({highlight:false});var c=b.join("_");var a=c+"_content";log("li_dom_id "+c);log("li_content_dom_id "+a);Docs.expandOperation($("#"+a));$("#"+c).slideto({highlight:false});break}},toggleEndpointListForResource:function(b){var a=$("li#resource_"+Docs.escapeResourceName(b)+" ul.endpoints");if(a.is(":visible")){Docs.collapseEndpointListForResource(b)}else{Docs.expandEndpointListForResource(b)}},expandEndpointListForResource:function(b){var b=Docs.escapeResourceName(b);if(b==""){$(".resource ul.endpoints").slideDown();return}$("li#resource_"+b).addClass("active");var a=$("li#resource_"+b+" ul.endpoints");a.slideDown()},collapseEndpointListForResource:function(b){var b=Docs.escapeResourceName(b);$("li#resource_"+b).removeClass("active");var a=$("li#resource_"+b+" ul.endpoints");a.slideUp()},expandOperationsForResource:function(a){Docs.expandEndpointListForResource(a);if(a==""){$(".resource ul.endpoints li.operation div.content").slideDown();return}$("li#resource_"+Docs.escapeResourceName(a)+" li.operation div.content").each(function(){Docs.expandOperation($(this))})},collapseOperationsForResource:function(a){Docs.expandEndpointListForResource(a);$("li#resource_"+Docs.escapeResourceName(a)+" li.operation div.content").each(function(){Docs.collapseOperation($(this))})},escapeResourceName:function(a){return a.replace(/[!"#$%&'()*+,.\/:;<=>?@\[\\\]\^`{|}~]/g,"\\$&")},expandOperation:function(a){a.slideDown()},collapseOperation:function(a){a.slideUp()}};(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.content_type=b(function(g,l,f,k,j){this.compilerInfo=[4,">= 1.0.0"];f=this.merge(f,g.helpers);j=j||{};var i="",c,h="function",m=this;function e(r,q){var o="",p;o+="\n ";p=f.each.call(r,r.produces,{hash:{},inverse:m.noop,fn:m.program(2,d,q),data:q});if(p||p===0){o+=p}o+="\n";return o}function d(r,q){var o="",p;o+='\n \n ";return o}function n(p,o){return'\n \n'}i+='\n\n";return i})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.main=b(function(g,m,f,l,k){this.compilerInfo=[4,">= 1.0.0"];f=this.merge(f,g.helpers);k=k||{};var i="",c,h="function",j=this.escapeExpression,p=this;function e(v,u){var r="",t,s;r+='\n
") + "
'+j(((t=((t=v.info),t==null||t===false?t:t.title)),typeof t===h?t.apply(v):t))+'
\n ';s=((t=((t=v.info),t==null||t===false?t:t.description)),typeof t===h?t.apply(v):t);if(s||s===0){r+=s}r+="
\n ";s=f["if"].call(v,((t=v.info),t==null||t===false?t:t.termsOfServiceUrl),{hash:{},inverse:p.noop,fn:p.program(2,d,u),data:u});if(s||s===0){r+=s}r+="\n ";s=f["if"].call(v,((t=v.info),t==null||t===false?t:t.contact),{hash:{},inverse:p.noop,fn:p.program(4,q,u),data:u});if(s||s===0){r+=s}r+="\n ";s=f["if"].call(v,((t=v.info),t==null||t===false?t:t.license),{hash:{},inverse:p.noop,fn:p.program(6,o,u),data:u});if(s||s===0){r+=s}r+="\n ";return r}function d(u,t){var r="",s;r+='';return r}function q(u,t){var r="",s;r+="';return r}function o(u,t){var r="",s;r+="";return r}function n(u,t){var r="",s;r+='\n , api version: ';if(s=f.apiVersion){s=s.call(u,{hash:{},data:t})}else{s=u.apiVersion;s=typeof s===h?s.apply(u):s}r+=j(s)+"\n ";return r}i+="\n ";c=f["if"].call(m,m.info,{hash:{},inverse:p.noop,fn:p.program(1,e,k),data:k});if(c||c===0){i+=c}i+="\n
\n\n
\n";return i})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.operation=b(function(h,n,g,m,l){this.compilerInfo=[4,">= 1.0.0"];g=this.merge(g,h.helpers);l=l||{};var j="",d,i="function",k=this.escapeExpression,r=this;function f(v,u){var s="",t;s+="\n - \n
Implementation Notes
\n";if(t=g.notes){t=t.call(v,{hash:{},data:u})}else{t=v.notes;t=typeof t===i?t.apply(v):t}if(t||t===0){s+=t}s+="
\n ";return s}function c(t,s){return'\nResponse Class
\n\n
\n \n '}function q(t,s){return'\n
Parameters
\n| Parameter | \nValue | \nDescription | \nParameter Type | \nData Type | \n
|---|
Error Status Codes
\n| HTTP Status Code | \nReason | \n
|---|
\n \n \n \n
\n "}j+="\n - \n
- \n \n \n \n
\n \n ';return u}function e(x,w){var u="",v;u+="\n ";v=o["if"].call(x,x.defaultValue,{hash:{},inverse:n.program(12,r,w),fn:n.program(10,t,w),data:w});if(v||v===0){u+=v}u+="\n ";return u}function t(x,w){var u="",v;u+="\n \n ";return u}function r(x,w){var u="",v;u+="\n \n ";return u}p+="
\n \n ';return w}function e(z,y){var w="",x;w+="\n ";x=o["if"].call(z,z.isFile,{hash:{},inverse:n.program(12,t,y),fn:n.program(10,v,y),data:y});if(x||x===0){w+=x}w+="\n ";return w}function v(z,y){var w="",x;w+="\n \n ";return w}function t(z,y){var w="",x;w+="\n ";x=o["if"].call(z,z.defaultValue,{hash:{},inverse:n.program(15,r,y),fn:n.program(13,s,y),data:y});if(x||x===0){w+=x}w+="\n ";return w}function s(z,y){var w="",x;w+="\n \n ";return w}function r(z,y){var w="",x;w+="\n \n ";return w}p+="
\n
\n\n";return h})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.response_content_type=b(function(g,l,f,k,j){this.compilerInfo=[4,">= 1.0.0"];f=this.merge(f,g.helpers);j=j||{};var i="",c,h="function",m=this;function e(r,q){var o="",p;o+="\n ";p=f.each.call(r,r.produces,{hash:{},inverse:m.noop,fn:m.program(2,d,q),data:q});if(p||p===0){o+=p}o+="\n";return o}function d(r,q){var o="",p;o+='\n \n ";return o}function n(p,o){return'\n \n'}i+='\n\n";return i})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.signature=b(function(e,k,d,j,i){this.compilerInfo=[4,">= 1.0.0"];d=this.merge(d,e.helpers);i=i||{};var g="",c,f="function",h=this.escapeExpression;g+='\n ";if(c=e.name){c=c.call(l,{hash:{},data:j})}else{c=l.name;c=typeof c===g?c.apply(l):c}h+=i(c)+" ";o={hash:{},inverse:n.noop,fn:n.program(1,d,j),data:j};if(c=e.description){c=c.call(l,o)}else{c=l.description;c=typeof c===g?c.apply(l):c}if(!e.description){c=m.call(l,c,o)}if(c||c===0){h+=c}if(c=e.description){c=c.call(l,{hash:{},data:j})}else{c=l.description;c=typeof c===g?c.apply(l):c}if(c||c===0){h+=c}h+="\n
\n \n\n
- \n
- Model \n
- Model Schema \n
\n\n";if(c=d.code){c=c.call(k,{hash:{},data:i})}else{c=k.code;c=typeof c===f?c.apply(k):c}g+=h(c)+" \n";if(c=d.message){c=c.call(k,{hash:{},data:i})}else{c=k.message;c=typeof c===f?c.apply(k):c}if(c||c===0){g+=c}g+=" \n";return g})})();(function(){var j,r,u,o,l,k,n,m,i,p,s,q,h,c,g,f,e,d,b,a,x,w,t={}.hasOwnProperty,v=function(B,z){for(var y in z){if(t.call(z,y)){B[y]=z[y]}}function A(){this.constructor=B}A.prototype=z.prototype;B.prototype=new A();B.__super__=z.prototype;return B};s=(function(z){v(y,z);function y(){q=y.__super__.constructor.apply(this,arguments);return q}y.prototype.dom_id="swagger_ui";y.prototype.options=null;y.prototype.api=null;y.prototype.headerView=null;y.prototype.mainView=null;y.prototype.initialize=function(A){var B=this;if(A==null){A={}}if(A.dom_id!=null){this.dom_id=A.dom_id;delete A.dom_id}if($("#"+this.dom_id)==null){$("body").append('')}this.options=A;this.options.success=function(){return B.render()};this.options.progress=function(C){return B.showMessage(C)};this.options.failure=function(C){return B.onLoadFailure(C)};this.headerView=new r({el:$("#header")});return this.headerView.on("update-swagger-ui",function(C){return B.updateSwaggerUi(C)})};y.prototype.updateSwaggerUi=function(A){this.options.url=A.url;return this.load()};y.prototype.load=function(){var B,A;if((A=this.mainView)!=null){A.clear()}B=this.options.url;if(B.indexOf("http")!==0){B=this.buildUrl(window.location.href.toString(),B)}this.options.url=B;this.headerView.update(B);this.api=new SwaggerApi(this.options);this.api.build();return this.api};y.prototype.render=function(){var A=this;this.showMessage("Finished Loading Resource Information. Rendering Swagger UI...");this.mainView=new u({model:this.api,el:$("#"+this.dom_id)}).render();this.showMessage();switch(this.options.docExpansion){case"full":Docs.expandOperationsForResource("");break;case"list":Docs.collapseOperationsForResource("")}if(this.options.onComplete){this.options.onComplete(this.api,this)}return setTimeout(function(){return Docs.shebang()},400)};y.prototype.buildUrl=function(C,A){var B,D;log("base is "+C);if(A.indexOf("/")===0){D=C.split("/");C=D[0]+"//"+D[2];return C+A}else{B=C.length;if(C.indexOf("?")>-1){B=Math.min(B,C.indexOf("?"))}if(C.indexOf("#")>-1){B=Math.min(B,C.indexOf("#"))}C=C.substring(0,B);if(C.indexOf("/",C.length-1)!==-1){return C+A}return C+"/"+A}};y.prototype.showMessage=function(A){if(A==null){A=""}$("#message-bar").removeClass("message-fail");$("#message-bar").addClass("message-success");return $("#message-bar").html(A)};y.prototype.onLoadFailure=function(A){var B;if(A==null){A=""}$("#message-bar").removeClass("message-success");$("#message-bar").addClass("message-fail");B=$("#message-bar").html(A);if(this.options.onFailure!=null){this.options.onFailure(A)}return B};return y})(Backbone.Router);window.SwaggerUi=s;r=(function(z){v(y,z);function y(){h=y.__super__.constructor.apply(this,arguments);return h}y.prototype.events={"click #show-pet-store-icon":"showPetStore","click #show-wordnik-dev-icon":"showWordnikDev","click #explore":"showCustom","keyup #input_baseUrl":"showCustomOnKeyup","keyup #input_apiKey":"showCustomOnKeyup"};y.prototype.initialize=function(){};y.prototype.showPetStore=function(A){return this.trigger("update-swagger-ui",{url:"http://petstore.swagger.wordnik.com/api/api-docs"})};y.prototype.showWordnikDev=function(A){return this.trigger("update-swagger-ui",{url:"http://api.wordnik.com/v4/resources.json"})};y.prototype.showCustomOnKeyup=function(A){if(A.keyCode===13){return this.showCustom()}};y.prototype.showCustom=function(A){if(A!=null){A.preventDefault()}return this.trigger("update-swagger-ui",{url:$("#input_baseUrl").val(),apiKey:$("#input_apiKey").val()})};y.prototype.update=function(B,C,A){if(A==null){A=false}$("#input_baseUrl").val(B);if(A){return this.trigger("update-swagger-ui",{url:B})}};return y})(Backbone.View);u=(function(y){v(z,y);function z(){g=z.__super__.constructor.apply(this,arguments);return g}z.prototype.initialize=function(){};z.prototype.render=function(){var B,G,D,E,C,A,F;$(this.el).html(Handlebars.templates.main(this.model));E={};B=0;F=this.model.apisArray;for(C=0,A=F.length;C0){D[I.name]=I.value}if(I.type==="file"){N=true}}E=G.find("textarea");for(L=0,F=E.length;L0){D.body=I.value}}B=G.find("select");for(K=0,C=B.length;K0){D[I.name]=J}}A.responseContentType=$("div select[name=responseContentType]",$(this.el)).val();A.requestContentType=$("div select[name=parameterContentType]",$(this.el)).val();$(".response_throbber",$(this.el)).show();if(N){return this.handleFileUpload(D,G)}else{return this.model["do"](D,A,this.showCompleteStatus,this.showErrorStatus,this)}}};y.prototype.success=function(A,B){return B.showCompleteStatus(A)};y.prototype.handleFileUpload=function(Q,I){var M,H,C,N,L,K,J,G,E,D,P,T,S,R,F,B,A,U,O=this;log("it's a file upload");F=I.serializeArray();for(J=0,P=F.length;J0){Q[N.name]=N.value}}M=new FormData();B=this.model.parameters;for(G=0,T=B.length;G"+this.invocationUrl+"");L={type:this.model.method,url:this.invocationUrl,headers:C,data:M,dataType:"json",contentType:false,processData:false,error:function(W,X,V){return O.showErrorStatus(O.wrap(W),O)},success:function(V){return O.showResponse(V,O)},complete:function(V){return O.showCompleteStatus(O.wrap(V),O)}};if(window.authorizations){window.authorizations.apply(L)}jQuery.ajax(L);return false};y.prototype.wrap=function(E){var F,H,A,G,D,C,B;H={};F=E.getAllResponseHeaders().split(":");for(A=D=0,C=F.length/2,B=2;B>0?D<=C:D>=C;A=D+=B){H[F[A]]=F[A+1]}G={};G.content={};G.content.data=E.responseText;G.headers=H;G.request={};G.request.url=this.invocationUrl;G.status=E.status;return G};y.prototype.getSelectedValue=function(A){var D,C,F,B,E;if(!A.multiple){return A.value}else{C=[];E=A.options;for(F=0,B=E.length;F0){return C.join(",")}else{return null}}};y.prototype.hideResponse=function(A){if(A!=null){A.preventDefault()}$(".response",$(this.el)).slideUp();return $(".response_hider",$(this.el)).fadeOut()};y.prototype.showResponse=function(A){var B;B=JSON.stringify(A,null,"\t").replace(/\n/g,"
");return $(".response_body",$(this.el)).html(escape(B))};y.prototype.showErrorStatus=function(B,A){return A.showStatus(B)};y.prototype.showCompleteStatus=function(B,A){return A.showStatus(B)};y.prototype.formatXml=function(H){var D,G,B,I,N,J,C,A,L,M,F,E,K;A=/(>)(<)(\/*)/g;M=/[ ]*(.*)[ ]+\n/g;D=/(<.+>)(.+\n)/g;H=H.replace(A,"$1\n$2$3").replace(M,"$1\n").replace(D,"$1\n$2");C=0;G="";N=H.split("\n");B=0;I="other";L={"single->single":0,"single->closing":-1,"single->opening":0,"single->other":0,"closing->single":0,"closing->closing":-1,"closing->opening":0,"closing->other":0,"opening->single":1,"opening->closing":0,"opening->opening":1,"opening->other":1,"other->single":0,"other->closing":-1,"other->opening":0,"other->other":0};F=function(T){var P,O,R,V,S,Q,U;Q={single:Boolean(T.match(/<.+\/>/)),closing:Boolean(T.match(/<\/.+>/)),opening:Boolean(T.match(/<[^!?].*>/))};S=((function(){var W;W=[];for(R in Q){U=Q[R];if(U){W.push(R)}}return W})())[0];S=S===void 0?"other":S;P=I+"->"+S;I=S;V="";B+=L[P];V=((function(){var X,Y,W;W=[];for(O=X=0,Y=B;0<=Y?XY;O=0<=Y?++X:--X){W.push(" ")}return W})()).join("");if(P==="opening->closing"){return G=G.substr(0,G.length-1)+T+"\n"}else{return G+=V+T+"\n"}};for(E=0,K=N.length;E![]()
").attr("src",B)}else{E=$(".
+
+*** Note this is a placeholder registry. Don't take the values seriously. ***
+
+Inital contents of the registry will include:
+
+|Name |Link |Description |
+|--- | --- | --- |
+|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema |
+
+## Backwards compatibility
+
+This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly.
+
+## Alternatives considered
+
+Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language.
+
diff --git a/proposals/002_Webhooks.md b/proposals/002_Webhooks.md
new file mode 100644
index 0000000000..8ad8a97fa9
--- /dev/null
+++ b/proposals/002_Webhooks.md
@@ -0,0 +1,192 @@
+# Webhooks
+
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)|
+|Authors|[Lorna Mitchell](https://github.com/lornajane)|
+|Review Manager |TBD |
+|Status |Proposal|
+|Issues |[#1968](https://github.com/OAI/OpenAPI-Specification/issues/1968)|
+
+## Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+| 17th July 2019 | Lorna Mitchell | Initial draft |
+
+## Introduction
+
+Modern APIs often consist of two-way API traffic, but OpenAPI currently only supports some types of requests. Standard client-to-server API calls are well supported. Server-to-client callbacks are only supported if they are the result of an earlier API call and are documented by nesting under the path of that earlier call. Incoming HTTP reqests ("webhooks") cannot be described in the current version of OpenAPI if they are the result of subscription arranged outside of the scope of the API (e.g. by setting a callback URL in a web interface).
+
+## Motivation
+
+OpenAPI supports a `callback` element, where the result of an API call is delivered at some later time as an incoming HTTP request to a nominated URL. However it does not support webhooks, where events arrive as an incoming HTTP request but the configuration of these requests was arranged outside of the scope of the API, e.g. on a website.
+
+For example: at Nexmo we have an SMS API (the docs are here: and the source spec here: ). It supports:
+
+* sending an SMS (an outgoing API call, currently supported)
+* receiving a delivery receipt when you just sent an SMS (callback, currently supported)
+* receiving an incoming SMS (webhook, not currently supported)
+
+The docs have an `x-webhooks` top-level element (we use [our own docs renderer](https://github.com/Nexmo/nexmo-oas-renderer)) and then a meaningless URL fieldname before the path item object that descrives the webhook.
+
+On one of the other Nexmo APIs, we simply documented our webhooks in a markdown file separate from our API even though the two directions are very closely linked (see [Voice API webhook reference](https://developer.nexmo.com/voice/voice-api/webhook-reference) ).
+
+Neither solution is great. I'm aware of other organisations (Ebay, GitHub) who also offer webhooks as part of their API platform who have run into the same problems when looking to adopt OpenAPI. The existing approach for callbacks, which allow a Path Item Object to be described in another location, could be adapted to also describe webhooks.
+
+## Proposed solution
+
+Allow a top-level `webhooks` element, with named entries inside it, each containing a Path Item Object. No other new fields or changes would be needed, since this already works brilliantly for `callbacks` within a path item. The only difference here is that there's no existing path item for the callback/webhook to belong to, and the URL is usually set somewhere else by the user (and there's no request context for an expression to be evaluated).
+
+This solution builds on the existing proven approach for callbacks, but detaches them from the following-a-previous-API-call constraint.
+
+To borrow the Nexmo SMS API example from above (because it's simple, I can add more examples as needed), the spec for the incoming webhook that occurs because a message has arrived might look like this:
+
+```
+webhooks:
+ inbound-sms:
+ post:
+ summary: Inbound SMS to your Nexmo number
+ operationId: inbound-sms
+ description: |
+ If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your [webhook endpoint](https://developer.nexmo.com/concepts/guides/webhooks).
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - msisdn
+ - to
+ - messageid
+ - text
+ - type
+ - keyword
+ - message-timestamp
+ properties:
+ msisdn:
+ type: string
+ description: the phone number that this inbound message was sent from. numbers are specified in e.164 format.
+ example: '447700900001'
+ to:
+ type: string
+ description: the phone number the message was sent to. **this is your virtual number**. numbers are specified in e.164 format.
+ example: '447700900000'
+ messageid:
+ type: string
+ description: the id of the message
+ example: 0a0000000123abcd1
+ text:
+ type: string
+ description: The message body for this inbound message.
+ example: Hello world
+ type:
+ type: string
+ description: |
+ Possible values are:
+
+ - `text` - standard text.
+ - `unicode` - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
+ - `binary` - a binary message.
+ example: 'text'
+ keyword:
+ type: string
+ description: The first word in the message body. This is typically used with short codes.
+ example: Hello
+ message-timestamp:
+ description: The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.
+ type: string
+ example: 2020-01-01 12:00:00
+ responses:
+ '200':
+ description: |
+ Your server returns this code if it accepts the callback. Note that
+ Nexmo will retry messages that are not successfully acknowledged.
+```
+
+## Detailed design
+
+### Add the `webhooks` top-level element to the list
+
+**Existing Spec:**
+
+```
+#### OpenAPI Object
+
+This is the root document object of the [OpenAPI document](#oasDocument).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
+info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
+paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
+components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
+tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+```
+
+**Change: Add to the end of the table**
+
+```
+webhooks | [[Webhooks Object](#webhooksObject)] | The incoming webhooks that may be received as part of this API.
+```
+
+### Describe a new Webhook Object
+
+(new spec section)
+
+```
+#### Webhooks Object
+
+A map of webhooks that may be received as incoming HTTP requests as part of the API. The key of the map is a unique short name for the webhook e.g. `messageEvent`. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses.
+
+Webhook Objects differ from [Callback Objects](#callbackObject) in that the webhooks are the result of some external event, not an earlier API call to subscribe or cause some other effect.
+
+##### Webhook Object Example
+
+The following example shows an incoming webhook delivering a status update for a particular item ID:
+
+````yaml
+webhooks:
+ statusUpdate:
+ requestBody:
+ description: Status updates on an item. You can set the URL for these updates in your example.com dashboard.
+ content:
+ 'application/json':
+ schema:
+ type: object
+ required:
+ - item_id
+ - status
+ properties:
+ item_id:
+ type: string
+ description: The ID of the item
+ example: 0a000000012345678
+ status:
+ type: integer
+ description: The status of this message, zero for success
+ example: 14
+ responses:
+ '200':
+ description: webhook successfully processed and no retries will be performed
+
+```
+
+## Backwards compatibility
+
+Adding a new top-level entry is not something to take lightly, however hopefully most tools will simply ignore what they weren't expecting and continue to operate on the parts of the spec they do understand until their functionality catches up with the spec change.
+
+## Alternatives considered
+
+Another option is to add a special `path` that could contain the various webhooks using the exisiting `callback` syntax but existing tools which aren't expecting this special value may not handle it well, so this option was discounted.
diff --git a/proposals/003_Clarify-Nullable.md b/proposals/003_Clarify-Nullable.md
new file mode 100644
index 0000000000..139b0dceef
--- /dev/null
+++ b/proposals/003_Clarify-Nullable.md
@@ -0,0 +1,219 @@
+# Clarify Semantics of `nullable` in OpenAPI 3.0
+
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/003_Clarify-Nullable.md)|
+|Authors|[Ted Epstein](https://github.com/tedepstein)|
+|Review Manager |TBD|
+|Status |Proposal|
+|Implementations |N/A|
+|Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957), [2057](https://github.com/OAI/OpenAPI-Specification/issues/2057)|
+|Previous Revisions |N/A |
+
+## Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- |------------|
+|Oct 31, 2019 | Ted Epstein | Initial proposal |
+
+## Introduction
+
+This proposal aims to clarify the semantics of the `nullable` keyword in OpenAPI 3.0. This clarification would resolve ambiguities, reinforce the intended alignment with JSON Schema, and provide guidance for schema validators, translators, and other tools.
+
+## Motivation
+
+The documentation of the `nullable` keyword is incomplete and ambiguous, leaving many questions unanswered, and causing significant difficulty in reconciling certain assumed semantics with JSON Schema.
+
+To summarize the problems:
+
+* `nullable: true` is an _expanding assertion_ that doesn't fit JSON Schema's constraint-based processing model. It is not clear how it interacts with other keywords, and within what scope.
+
+* `nullable: false`, which is the default value, is not clearly defined, and could be interpreted in a way that breaks fundamental assumptions of JSON Schema.
+
+* Different OpenAPI schema validators and other tool implementations are likely to have different behaviors because the semantics of `nullable` are not fully specified.
+
+* Because of the above ambiguities, it is not clear how to translate an OpenAPI Schema Object into a standard JSON Schema for message validation and for other purposes. Some possible interpretations of the OpenAPI spec could make translating to JSON Schema much more difficult.
+
+* Depending on the interpretation, `nullable` might interact with `oneOf` and `anyOf` in problematic and counter-intuitive ways.
+
+The solution proposed herein should:
+
+* Clarify the boundaries around `nullable` so we know how it interacts with other assertions, applicators, subtypes and supertypes within its context.
+
+* Clarify the meaning of `nullable: false`.
+
+* Reaffirm the intended alignment of OpenAPI's Schema Object with JSON Schema, and reconcile `nullable` with JSON Schema semantics.
+
+* Allow a straightforward translation from `nullable` in OpenAPI to type arrays in JSON Schema.
+
+Further details follow.
+
+### Primary Use Case for `nullable`
+
+A Schema Object allows values of any data type, unless the type is restricted by the `type` keyword. The `type` keyword restricts the schema to a single data type, which can be `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"`, or `"object"`, but cannot be `"null"`.
+
+Some APIs restrict values to a single data type, but also allow explicit null values. OpenAPI Schema Objects can allow explicit null values by combining the `type` and `nullable` keywords. A `nullable` value of `true` modifies a typed schema to allow non-null values of a given type, and also allow `null`. This was the envisioned use case, and the primary motivation for introducing `nullable` into the OpenAPI 3.0 spec.
+
+There may be other possible usage scenarios or consequences of the `nullable` keyword, the way it is specified, or the way in which the spec may be interpreted or implemented. In our view, these other scenarios should be considered side effects or oversights. To the best of our knowledge, the `nullable` keyword was not intended for any purpose other than to allow `null` in a typed schema.
+
+### Expanding vs. Constraining Assertions
+
+`nullable: true` is an _expanding assertion_, meaning it has the effect of expanding the range of acceptable values. By contrast, JSON Schema's central operating principle is constraint-based, where _constraining assertions_ are cumulative, immutable, and each constraint has veto power to disallow some range of values.
+
+The semantics of constraining assertions are well-defined by JSON Schema and implemented in many JSON Schema validators and other tools. But JSON Schema doesn't have expanding assertions, so those well-defined semantics don't apply to `nullable`.
+
+To address this, we need to translate `nullable: true` into a constraining assertion. Otherwise, we would have to specify in detail how `nullable` interacts with constraining assertions like `enum` and with boolean applicators like `allOf` and `anyOf`.
+
+### Interpretation of `nullable: false`
+
+The documentation specifies that `nullable: false` is the default, but doesn't clearly state what that means.
+
+One reasonable interpretation suggests that null values are disallowed unless `nullable` is explicitly set to `true`. This breaks a fundamental rule of JSON Schema, which states that an empty object `{}` is a valid schema that permits all values, with no constraints. Breaking that rule takes OpenAPI's Schema Object even further out of alignment with JSON Schema's processing model.
+
+For example, if null values are disallowed by default, does the following `UTCDate` schema accept `null`?
+
+```yaml
+components:
+
+ schemas:
+
+ OptionalDate:
+ type: string
+ format: date
+ nullable: true
+
+ UTCDate:
+ allOf:
+ - $ref: "#/components/schemas/OptionalDate"
+ not:
+ type: string
+ pattern: "^.*Z.*$"
+```
+
+`UTCDate` does not specify a type of its own, and does not directly specify `nullable: true`. So if `null` is disallowed by default, even for untyped schemas, then `UTCDate` won't accept nulls. If we want it to accept nulls, we have to repeat `nullable: true` in `UTCDate`. This is not at all intuitive for API designers, and it breaks with JSON Schema's rule that any value is allowed unless it's explicitly disallowed.
+
+On the other hand, we could say that `UTCDate` inherits `nullable: true` from `OptionalDate`, therefore null values are allowed. But this kind of inheritance logic is completely foreign to JSON Schema. So this behavior is also counterintuitive, though for a different reason. It's also difficult to implement. Any JSON Schema validator would need to be hacked in highly disruptive ways to retrofit this behavior. Or a preprocessor would have to be introduced to propagate the effect of `nullable: true` through the `*Of` inheritance hierarchy.
+
+Whichever semantics we choose, it gets very messy.
+
+### A closer look at `nullable: false`
+
+In fact, the OpenAPI 3.0 specification doesn't explicitly say that untyped schemas disallow null values.
+
+Here are the relevant parts:
+
+#### Data Types
+> Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00.
+
+To say that null is "not supported _as a type_" would definitely disallow `type: "null"` in a schema object. But it doesn't necessarily mean that an untyped schema disallows _null values_.
+
+#### Definition of `nullable`
+> Allows sending a null value for the defined schema. Default value is false.
+
+This uses the word "allows," but there's no mention of "disallows." To say that `nullable: true` _allows_ null where it would otherwise be prohibited, doesn't necessarily mean that `nullable: false` _disallows_ null where it would otherwise be allowed.
+
+`nullable: true` _modifies_ a typed schema by adding null to the allowed types. `nullable: false` could mean "no null values allowed" or it could just mean "no modification to the specified type assertion, if any."
+
+#### Schema Object
+> The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
+>
+> type - Value MUST be a string. Multiple types via an array are not supported.
+
+There is no specified adjustment to the `type` property that disallows null values. So it should defer to the JSON Schema specification, which says that, in the absence of a `type` assertion, any valid JSON value is allowed.
+
+So the 3.0 spec is ambiguous about null values. It's not clear whether the spec intended to disallow null values by default, even in untyped schemas. This looks more like an accidental oversight, or an unfortunate choice of words, than a clear intention.
+
+### Specific Questions
+
+Questions that are not answered by the current specification include the following:
+
+* If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).)
+
+* Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema?
+
+* Can `allOf` be used to define a nullable subtype of a non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)
+
+* Can `allOf` be used to define a non-nullable subtype of a nullable base schema?
+
+* What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema?
+
+* Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).)
+
+## Proposed solution
+
+We propose to clarify the 3.0 specification in the next patch release, to resolve these questions and align OpenAPI's Schema Object with JSON Schema's well-defined, constraint-based semantics.
+
+In our view, and consistent with the original intent, `nullable` should have a very limited, well-defined scope. It should satisfy the primary use case, i.e. allowing `null` in a typed schema, with minimal side effects.
+
+This is the proposed replacement for the `nullable` definition:
+
+ +Field Name | Type | Description +---|:---:|--- +nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. +
+ +## Detailed design + +According to the above specification, `nullable` only operates within a narrow scope, wherein its translation to JSON Schema is straightforward: + +* `nullable` is only meaningful if its value is `true`. + +* `nullable: true` is only meaningful in combination with a `type` assertion specified in the same Schema Object. `nullable` acts as a `type` modifier, allowing `null` in addition to the specified type. + +* `nullable: true` operates within a single Schema Object. It does not "override" or otherwise compete with supertype or subtype schemas defined with `allOf` or other applicators. It cannot be directly "inherited" through those applicators, and it cannot be applied to an inherited `type` constraint. + +This also solves the issues of alignment with JSON Schema: + +* Since `type` is a constraint, JSON Schema's constraint-based processing model is fully applicable. Interactions between `type` and other constraining assertions and applicators are unambiguous, with each constraint having independent veto power. + +* It is now clear that `nullable: false`, whether explicit or by default, _does not_ prohibit null values. Consistent with JSON Schema, an empty object allows all values, including `null`. + +### Questions Answered + +Following are answers to the questions posed above, assuming the proposed clarification is adopted: + +#### If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).) + +No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`. + +While the modified `type` now allows `null`, the `enum` does not. Consistent with JSON schema, a value conforms to the schema only if it is valid against _all_ constraints. Any constraint, in this case `enum`, can cause a value to fail validation, even if that value meets all of the other constraints. + +#### Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema? + +Yes, an untyped schema allows null values, in addition to all other types. `nullable: true` has no effect, because null values are already allowed. And `nullable: false` has no effect because it just leaves the `type` constraint unmodified. + +#### Can `allOf` be used to define a nullable subtype of a non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).) + +No. Subtypes can add constraints, but not relax them. + +#### Can `allOf` be used to define a non-nullable subtype of a nullable base schema? + +Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`. + +#### What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema? + +A nullable type should translate into a type array with two string elements: the name of the type specified in the Schema Object, and `"null"`. + +#### Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).) + +Yes. For example, a Schema Object with `"type" : "string", "nullable" : true` would translate to a JSON Schema with `"type" : ["string", "null"]`. That schema permits `"default" : null`, even with the [strict typing rule](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#properties) specified by OpenAPI 3.0: + +> default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. + +## Backwards compatibility + +Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations. + +With the clarification of `nullable: false`, we think the risk of actual breakage is miniscule, because the current ambiguity only affects untyped Schema Objects, which by their nature leave a lot of room for unexpected values. Any implementation that relies on schema validation to prevent null values should use explicitly typed schemas, and typed schemas unambiguously disallow `null` unless `nullable` is `true`. + +There might be a somewhat greater risk of breakage by specifying the effect of `nullable: true` as a `type` modifier. A more heavy-handed interpretation of `nullable: true`, [described here](https://github.com/OAI/OpenAPI-Specification/issues/1900#issuecomment-486772917), would make it equivalent to `anyOf [s, {type: "null"}]` where `s` is the schema as specified (excluding `nullable`). This would allow nulls even where they would be prohibited by other schema keywords, like `enum`. But this interpretation introduces far greater complexity than the narrowly scoped `type` modifier. We are not aware of any OpenAPI schema validator that actually attempts this, and there is nothing in the OpenAPI spec that says `nullable` can override constraining assertions. + +## Alternatives considered + +[Pull request #1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957) has some history of other approaches considered along the way. The first attempt assumed that `nullable: false` would prohibit null values, and attempted to work around this while maintaining backward compatibility. + +On closer inspection, the specification does not say anything about `null` values being disallowed. So we believe our interpretation is correct, and highly advantageous in its alignment with JSON Schema. diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md new file mode 100644 index 0000000000..de820558ba --- /dev/null +++ b/proposals/004_Overlays.md @@ -0,0 +1,232 @@ +# Overlays + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| +|Authors|[Darrel Miller](https://github.com/darrelmiller)| +|Status |Proposal| +|Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)| + +## Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | +| 24th December 2019 | Darrel Miller | Initial draft | +| 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.| +| 29th July 2020 | Darrel Miller | Updated to be explicit about update operations | + +## Introduction + +In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date. + +#### Overlay Document + +An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. + + +#### Overlay Object + +This is the root object of the [OpenAPI Overlay document](#oasDocument). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +overlay | `string` | Version of the Overlay specification that this document conforms to. +info | [[Info Object](#overlayInfoObject)] | Identifying information about the overlay. +extends | `url` | URL to an OpenAPI document this overlay applies to. +updates | [[Update Object](#updateObject)] | A list of update objects to be applied to the target document. + +The list of update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update. + +The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. This is an optional property. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description. + +#### Info Object + +This object contains identifying information about the [OpenAPI Overlay document](#oasDocument). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human readable description of the purpose of the overlay. +version | `string` | A version identifer for indicating changes to an overlay document. + +#### Update Object + +This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +target | `string` | A JMESPath expression referencing the target objects in the target document. +add | [Any](#addObject) | An object to be added as a child of the object(s) referenced by the target. Property has no impact if `remove` property is `true`. +merge | [Any](#mergeObject) | An object with the properties and values to be merged with the object(s) referenced by the target. Property has no impact if `remove` property is `true`. +remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false. + +The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object. + +##### Structured Overlays Example + +When updating properties throughout the target document it may be more efficient to create a single `Update Object` that mirrors the structure of the target document. e.g. + +```yaml +overlay: 1.0.0 +info: + title: Structured Overlay + version: 1.0.0 +updates: +- target: "@" + merge: + info: + x-overlay-applied: structured-overlay + paths: + "/": + summary: "The root resource" + get: + summary: "Retrieve the root resource" + x-rate-limit: 100 + "/pets": + get: + summary: "Retrieve a list of pets" + x-rate-limit: 100 + components: + tags: +``` + +##### Targeted Overlays + +Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted. + +```yaml +overlay: 1.0.0 +info: + title: Targeted Overlays + version: 1.0.0 +updates: +- target: paths."/foo".get + merge: + description: This is the new description +- target: paths."/bar".get + merge: + description: This is the updated description +- target: paths."/bar" + merge: + post: + description: This is an updated description of a child object + x-safe: false +``` + +##### Wildcard Overlays Examples + +One significant advantage of using the JMESPath syntax that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards. + +```yaml +overlay: 1.0.0 +info: + title: Update many objects at once + version: 1.0.0 +updates: +- target: paths.*.get + merge: + x-safe: true +- target: paths.*.get.parameters[?name=='filter' && in=='query'] + merge: + schema: + $ref: "/components/schemas/filterSchema" +``` + +##### Array Modification Examples + +Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the `remove` property. Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed. + +```yaml +overlay: 1.0.0 +info: + title: Add an array element + version: 1.0.0 +updates: +- target: paths.*.get.parameters + add: + name: newParam + in: query +``` + +```yaml +overlay: 1.0.0 +info: + title: Remove a array element + version: 1.0.0 +updates: +- target: paths[*].get.parameters[? name == 'dummy'] + remove: true +``` + +##### Traits Examples + +By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied. + +```yaml +openapi: 3.1.0 +info: + title: Api with a paged collection + version: 1.0.0 +paths: + /items: + get: + x-oai-traits: ["paged"] + responses: + 200: + description: OK +``` + +With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied. + +```yaml +overlay: 1.0.0 +info: + title: Apply Traits + version: 1.0.0 +updates: +- target: $.paths[*].get[?contains(x-traits,'paged')] + merge: + parameters: + - name: top + in: query + - name: skip + in: query +``` + +This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself. + +## Proposal Summary + +### Benefits + +- This approach addresses the two distinct approaches of structured overlay vs targeted overlay which suits distinct but equally valid scenarios. +- Addresses the problem of modifying the parameters array and removes the need to replace the entire array when a small change is required. +- Allows sets of related overlays to be stored in a same file. +- Enables updating a set of objects based on a pattern. This might be an effective way of apply common behaviour across many operations in an API. + +### Challenges + +- Tooling will need a JMESPath implementation. +- Large overlays may be slow to process. +- Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes. + +## Alternatives considered + +JMESPath was chosen over JSONPath due to the fact that JMESPath has a [specification](http://jmespath.org/specification.html) and a set of test cases. This will help to ensure compatibility between implementations. + +## Backwards compatibility + +Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions. + +## Scenarios Considered + +- Multi-language support. An Overlay document for each language is used to target a specific OpenAPI description. The Overlay document will likely use a duplicate structure to the original OpenAPI description and replace all `description` properties. +- Applying API wide standards. An Overlay document contains update objects that describe standard headers, parameters, responses. These documents would use JMESPath queries to target the appropriate objects in the OpenAPI description. Tooling could be used to target the OpenAPI description rather than using extends. +- Add tool specific OpenAPI metadata. Overlay adds additional metadata such as SLA information, client codegen hints or middleware policies. Using Overlays to manage this data separately is valuable when there is a different audience for the data and/or there the information has different sensitivity levels. diff --git a/proposals/Alternative Schema/CONTRIBUTORS.md b/proposals/Alternative Schema/CONTRIBUTORS.md new file mode 100644 index 0000000000..227901b37a --- /dev/null +++ b/proposals/Alternative Schema/CONTRIBUTORS.md @@ -0,0 +1,2 @@ +* Chuck Heazel [@cmheazel](https://github.com/cmheazel) +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) \ No newline at end of file diff --git a/proposals/Alternative Schema/DEVELOPMENT.md b/proposals/Alternative Schema/DEVELOPMENT.md new file mode 100644 index 0000000000..65ff4b1684 --- /dev/null +++ b/proposals/Alternative Schema/DEVELOPMENT.md @@ -0,0 +1,38 @@ +## Development Guidelines + +TBD + +## Specification Driving factors + +TBD + +## Specification Change Criteria + +TBD + +## Specification Change Process + +TBD + +## Tracking Process + +* GitHub is the medium of record for all spec designs, use cases, and so on. + + +## Release Process + +TBD + +## Draft Features + + +## Transparency + + + +## Participation + + + +## Community Roles + diff --git a/proposals/Alternative Schema/alternative_schema_examples.md b/proposals/Alternative Schema/alternative_schema_examples.md new file mode 100644 index 0000000000..96f7189576 --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_examples.md @@ -0,0 +1,53 @@ +## Change: Add Alternative Schema Examples + +The following text is to be inserted after the Alternative Schema Object section. + +### Alternative Schema Examples + +Minimalist usage of alternative schema: + + schema: + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + +Combination of OAS schema and alternative: + + schema: + type: object + nullable: true + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + +Multiple different versions of alternative schema: + + schema: + anyOf: + - x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema-08.json + - x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema-07.json + +Combined alternative schemas: + + schema: + allOf: + - x-oas-draft-alternativeSchema: + type: xmlSchema + location: ./xmlSchema.xsd + - x-oas-draft-alternativeSchema: + type: schematron + location: ./schema.sch + +Mixed OAS schema and alternative schema: + + schema: + type: array + items: + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.adoc new file mode 100644 index 0000000000..011f26b6b6 --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_object.adoc @@ -0,0 +1,16 @@ +## Change: Add the Alternative Schema Object + +The following text is to be inserted after the XML Object section + +### Alternative Schema Object + +This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed. + +==== Fixed Fields + +|Field Name | Type | Description | +|---|:---:|---| +|type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. | +|location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. | + +This object MAY be extended with Specification Extensions. diff --git a/proposals/Alternative Schema/implementations.md b/proposals/Alternative Schema/implementations.md new file mode 100644 index 0000000000..f1d61e48f2 --- /dev/null +++ b/proposals/Alternative Schema/implementations.md @@ -0,0 +1,46 @@ +# Implementations + +## Overview + +Below is a list of tooling that claims to implement the Alternative Schema proposal. While support for this feature matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the OpenAPI specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. + +These tools are not endorsed by the OAI + +## Implementations: + +#### Low-Level tooling + +| Title | Project Link | Language | Description +| ----------- | ----------- | ----------- | ----------- +|TBD |TBD |TBD |TBD | + +#### Editors + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### User Interfaces + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### Mock Servers +| Title | Project Link | Language | Description | +| -------------- | ------------ | -------- | ----------- | +|TBD |TBD |TBD |TBD | + +#### Server Implementations +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### Code Generators + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + + + diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md new file mode 100644 index 0000000000..df8c64c8ff --- /dev/null +++ b/proposals/Alternative Schema/schema_object.md @@ -0,0 +1,17 @@ +## Change: Extend the Schema Object to support Alternative Schemas + +The following content shall be used to replace the Fixed Fields table in the Schema Object section + +#### Fixed Fields + +|Field Name | Type | Description | +|---|:---:|---| +| nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.| +| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. | +| readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | +| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. +| example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.| +| deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.| +|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | diff --git a/proposals/Overlays/Changes.yml b/proposals/Overlays/Changes.yml new file mode 100644 index 0000000000..d2abf79e64 --- /dev/null +++ b/proposals/Overlays/Changes.yml @@ -0,0 +1,70 @@ +# Create update methods (add,replace,merge,delete)? Is merge necessary? +# Multiple additions or updates to the same target is more efficient with merge + +# Different than JSON Patch because is works in JSON and YAML +# Has info object and spec version +# values + +overlay: 1.0.0 +info: + title: An example of an overlay that captures changes to an API + version: 1.0.0 +updates: +# Add a property to a schema +- target: components.schemas."todo".properties + merge: + createdBy: + type: string +# Add constraints to a schema +- target: components.schemas."todo" + merge: + additionalProperties: false +- target: components.schemas."todo" + merge: + type: ["object","null"] +#Change a schema +- target: components.schemas."todo" + replace: + type: integer +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] + properties: + someprop: + type: string +# Add an operation +- target: paths."/foo" + add: + delete: + description: delete a foo + responses: + 200: + description: ok +# Add a path +- target: paths + add: + "/items": + get: + responses: + 200: + description: ok +# Add an optional query parameter +- target: paths."/bar".parameters + add: + name: skip + in: query + type: string +# Mark an operation as deprecated + +# Change the value of a JSON schema constraint +# Update the version of the API +# Change the license of an API +# Add support for a new request media type +# Add support for a new response media type diff --git a/proposals/Overlays/MergePatch.yml b/proposals/Overlays/MergePatch.yml new file mode 100644 index 0000000000..3bd4d0a1cb --- /dev/null +++ b/proposals/Overlays/MergePatch.yml @@ -0,0 +1,10 @@ +overlay: 1.0.0 +info: + title: An example of an overlay that performs a Merge Patch + version: 1.0.0 +updates: +- target: "@" + merge: + openapi: 3.0.3 + paths: {} + diff --git a/schemas/v2.0/README.md b/schemas/v2.0/README.md index becb22d06e..47b0c8e817 100644 --- a/schemas/v2.0/README.md +++ b/schemas/v2.0/README.md @@ -1,6 +1,6 @@ -# Swagger Specification JSON Schemas +# OpenAPI Specification v2.0 JSON Schema -This is only JSON Schema file for Swagger version 2.0. Download and Install it via NPM or Bower. +This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM. ## Install via NPM @@ -8,17 +8,6 @@ This is only JSON Schema file for Swagger version 2.0. Download and Install it v npm install --save swagger-schema-official ``` -#### Install 1.2 version via NPM - -```shell -npm install --save swagger-schema-official@1.2.0 -``` -## Install via Bower - - ```shell - bower install --save swagger-schema - ``` - ## License Apache-2.0 diff --git a/schemas/v2.0/bower.json b/schemas/v2.0/bower.json deleted file mode 100644 index 1049d27104..0000000000 --- a/schemas/v2.0/bower.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "swagger-schema", - "version": "2.0.0-96305d9", - "homepage": "https://github.com/swagger-api/swagger-schema", - "authors": [ - "''" - ], - "main": "./schema.json", - "description": "Swagger JSON Schema", - "keywords": [ - "swagger", - "schema", - "api" - ], - "license": "Apache-2.0" -} diff --git a/schemas/v2.0/package.json b/schemas/v2.0/package.json deleted file mode 100644 index 2c9d724182..0000000000 --- a/schemas/v2.0/package.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "swagger-schema-official", - "version": "2.0.0-bab6bed", - "description": "Swagger JSON Schema ", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "keywords": [ - "swagger", - "schema", - "api" - ], - "author": "", - "main": "./schema.json", - "license": "Apache-2.0" -} diff --git a/schemas/v3.0/README.md b/schemas/v3.0/README.md new file mode 100644 index 0000000000..84956279da --- /dev/null +++ b/schemas/v3.0/README.md @@ -0,0 +1,16 @@ +OpenAPI 3.0.X JSON Schema +--- + +Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.0.X. + +As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. + +The iteration version of the JSON Schema can be found in the `id` field. For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. + +To submit improvements to the schema, modify the schema.yaml file only. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Convert the schema.yaml to schema.json +- Publish the new version diff --git a/schemas/v3.0/schema.json b/schemas/v3.0/schema.json new file mode 100644 index 0000000000..71808402f6 --- /dev/null +++ b/schemas/v3.0/schema.json @@ -0,0 +1,1654 @@ +{ + "id": "https://spec.openapis.org/oas/3.0/schema/2019-04-02", + "$schema": "http://json-schema.org/draft-04/schema#", + "description": "Validation schema for OpenAPI Specification 3.0.X.", + "type": "object", + "required": [ + "openapi", + "info", + "paths" + ], + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.0\\.\\d(-.+)?$" + }, + "info": { + "$ref": "#/definitions/Info" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/SecurityRequirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/Tag" + }, + "uniqueItems": true + }, + "paths": { + "$ref": "#/definitions/Paths" + }, + "components": { + "$ref": "#/definitions/Components" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "definitions": { + "Reference": { + "type": "object", + "required": [ + "$ref" + ], + "patternProperties": { + "^\\$ref$": { + "type": "string", + "format": "uri-reference" + } + } + }, + "Info": { + "type": "object", + "required": [ + "title", + "version" + ], + "properties": { + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string", + "format": "uri-reference" + }, + "contact": { + "$ref": "#/definitions/Contact" + }, + "license": { + "$ref": "#/definitions/License" + }, + "version": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + }, + "email": { + "type": "string", + "format": "email" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "License": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Server": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ServerVariable" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ServerVariable": { + "type": "object", + "required": [ + "default" + ], + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + } + }, + "default": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "responses": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Response" + } + ] + } + } + }, + "parameters": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Parameter" + } + ] + } + } + }, + "examples": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Example" + } + ] + } + } + }, + "requestBodies": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/RequestBody" + } + ] + } + } + }, + "headers": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Header" + } + ] + } + } + }, + "securitySchemes": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/SecurityScheme" + } + ] + } + } + }, + "links": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Link" + } + ] + } + } + }, + "callbacks": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Callback" + } + ] + } + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Schema": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "multipleOf": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": true + }, + "maximum": { + "type": "number" + }, + "exclusiveMaximum": { + "type": "boolean", + "default": false + }, + "minimum": { + "type": "number" + }, + "exclusiveMinimum": { + "type": "boolean", + "default": false + }, + "maxLength": { + "type": "integer", + "minimum": 0 + }, + "minLength": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "pattern": { + "type": "string", + "format": "regex" + }, + "maxItems": { + "type": "integer", + "minimum": 0 + }, + "minItems": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "uniqueItems": { + "type": "boolean", + "default": false + }, + "maxProperties": { + "type": "integer", + "minimum": 0 + }, + "minProperties": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true + }, + "enum": { + "type": "array", + "items": { + }, + "minItems": 1, + "uniqueItems": false + }, + "type": { + "type": "string", + "enum": [ + "array", + "boolean", + "integer", + "number", + "object", + "string" + ] + }, + "not": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "allOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "oneOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "anyOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "properties": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + }, + { + "type": "boolean" + } + ], + "default": true + }, + "description": { + "type": "string" + }, + "format": { + "type": "string" + }, + "default": { + }, + "nullable": { + "type": "boolean", + "default": false + }, + "discriminator": { + "$ref": "#/definitions/Discriminator" + }, + "readOnly": { + "type": "boolean", + "default": false + }, + "writeOnly": { + "type": "boolean", + "default": false + }, + "example": { + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "xml": { + "$ref": "#/definitions/XML" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Discriminator": { + "type": "object", + "required": [ + "propertyName" + ], + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "XML": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean", + "default": false + }, + "wrapped": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Response": { + "type": "object", + "required": [ + "description" + ], + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Header" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Link" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "MediaType": { + "type": "object", + "properties": { + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Encoding" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + } + ] + }, + "Example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": { + }, + "externalValue": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string", + "enum": [ + "simple" + ], + "default": "simple" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + }, + { + "$ref": "#/definitions/SchemaXORContent" + } + ] + }, + "Paths": { + "type": "object", + "patternProperties": { + "^\\/": { + "$ref": "#/definitions/PathItem" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "PathItem": { + "type": "object", + "properties": { + "$ref": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Parameter" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "uniqueItems": true + } + }, + "patternProperties": { + "^(get|put|post|delete|options|head|patch|trace)$": { + "$ref": "#/definitions/Operation" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "Operation": { + "type": "object", + "required": [ + "responses" + ], + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Parameter" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "uniqueItems": true + }, + "requestBody": { + "oneOf": [ + { + "$ref": "#/definitions/RequestBody" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "responses": { + "$ref": "#/definitions/Responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Callback" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/SecurityRequirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Responses": { + "type": "object", + "properties": { + "default": { + "oneOf": [ + { + "$ref": "#/definitions/Response" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "patternProperties": { + "^[1-5](?:\\d{2}|XX)$": { + "oneOf": [ + { + "$ref": "#/definitions/Response" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "^x-": { + } + }, + "minProperties": 1, + "additionalProperties": false + }, + "SecurityRequirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExternalDocumentation": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "description": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExampleXORExamples": { + "description": "Example and examples are mutually exclusive", + "not": { + "required": [ + "example", + "examples" + ] + } + }, + "SchemaXORContent": { + "description": "Schema and content are mutually exclusive, at least one is required", + "not": { + "required": [ + "schema", + "content" + ] + }, + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ], + "description": "Some properties are not allowed if content is present", + "allOf": [ + { + "not": { + "required": [ + "style" + ] + } + }, + { + "not": { + "required": [ + "explode" + ] + } + }, + { + "not": { + "required": [ + "allowReserved" + ] + } + }, + { + "not": { + "required": [ + "example" + ] + } + }, + { + "not": { + "required": [ + "examples" + ] + } + } + ] + } + ] + }, + "Parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "type": "string" + }, + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "required": [ + "name", + "in" + ], + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + }, + { + "$ref": "#/definitions/SchemaXORContent" + }, + { + "$ref": "#/definitions/ParameterLocation" + } + ] + }, + "ParameterLocation": { + "description": "Parameter location", + "oneOf": [ + { + "description": "Parameter in path", + "required": [ + "required" + ], + "properties": { + "in": { + "enum": [ + "path" + ] + }, + "style": { + "enum": [ + "matrix", + "label", + "simple" + ], + "default": "simple" + }, + "required": { + "enum": [ + true + ] + } + } + }, + { + "description": "Parameter in query", + "properties": { + "in": { + "enum": [ + "query" + ] + }, + "style": { + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ], + "default": "form" + } + } + }, + { + "description": "Parameter in header", + "properties": { + "in": { + "enum": [ + "header" + ] + }, + "style": { + "enum": [ + "simple" + ], + "default": "simple" + } + } + }, + { + "description": "Parameter in cookie", + "properties": { + "in": { + "enum": [ + "cookie" + ] + }, + "style": { + "enum": [ + "form" + ], + "default": "form" + } + } + } + ] + }, + "RequestBody": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "description": { + "type": "string" + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + } + }, + "required": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "SecurityScheme": { + "oneOf": [ + { + "$ref": "#/definitions/APIKeySecurityScheme" + }, + { + "$ref": "#/definitions/HTTPSecurityScheme" + }, + { + "$ref": "#/definitions/OAuth2SecurityScheme" + }, + { + "$ref": "#/definitions/OpenIdConnectSecurityScheme" + } + ] + }, + "APIKeySecurityScheme": { + "type": "object", + "required": [ + "type", + "name", + "in" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "apiKey" + ] + }, + "name": { + "type": "string" + }, + "in": { + "type": "string", + "enum": [ + "header", + "query", + "cookie" + ] + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "HTTPSecurityScheme": { + "type": "object", + "required": [ + "scheme", + "type" + ], + "properties": { + "scheme": { + "type": "string" + }, + "bearerFormat": { + "type": "string" + }, + "description": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "http" + ] + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "oneOf": [ + { + "description": "Bearer", + "properties": { + "scheme": { + "enum": [ + "bearer" + ] + } + } + }, + { + "description": "Non Bearer", + "not": { + "required": [ + "bearerFormat" + ] + }, + "properties": { + "scheme": { + "not": { + "enum": [ + "bearer" + ] + } + } + } + } + ] + }, + "OAuth2SecurityScheme": { + "type": "object", + "required": [ + "type", + "flows" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "oauth2" + ] + }, + "flows": { + "$ref": "#/definitions/OAuthFlows" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OpenIdConnectSecurityScheme": { + "type": "object", + "required": [ + "type", + "openIdConnectUrl" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "openIdConnect" + ] + }, + "openIdConnectUrl": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OAuthFlows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/definitions/ImplicitOAuthFlow" + }, + "password": { + "$ref": "#/definitions/PasswordOAuthFlow" + }, + "clientCredentials": { + "$ref": "#/definitions/ClientCredentialsFlow" + }, + "authorizationCode": { + "$ref": "#/definitions/AuthorizationCodeOAuthFlow" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ImplicitOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "scopes" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "PasswordOAuthFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ClientCredentialsFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "AuthorizationCodeOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "tokenUrl" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Link": { + "type": "object", + "properties": { + "operationId": { + "type": "string" + }, + "operationRef": { + "type": "string", + "format": "uri-reference" + }, + "parameters": { + "type": "object", + "additionalProperties": { + } + }, + "requestBody": { + }, + "description": { + "type": "string" + }, + "server": { + "$ref": "#/definitions/Server" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "not": { + "description": "Operation Id and Operation Ref are mutually exclusive", + "required": [ + "operationId", + "operationRef" + ] + } + }, + "Callback": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/PathItem" + }, + "patternProperties": { + "^x-": { + } + } + }, + "Encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Header" + } + }, + "style": { + "type": "string", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + } + }, + "additionalProperties": false + } + } +} \ No newline at end of file diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml new file mode 100644 index 0000000000..13e47ff08d --- /dev/null +++ b/schemas/v3.0/schema.yaml @@ -0,0 +1,1003 @@ +id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 +$schema: http://json-schema.org/draft-04/schema# +description: Validation schema for OpenAPI Specification 3.0.X. +type: object +required: + - openapi + - info + - paths +properties: + openapi: + type: string + pattern: ^3\.0\.\d(-.+)?$ + info: + $ref: '#/definitions/Info' + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + servers: + type: array + items: + $ref: '#/definitions/Server' + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + tags: + type: array + items: + $ref: '#/definitions/Tag' + uniqueItems: true + paths: + $ref: '#/definitions/Paths' + components: + $ref: '#/definitions/Components' +patternProperties: + '^x-': {} +additionalProperties: false +definitions: + Reference: + type: object + required: + - $ref + patternProperties: + '^\$ref$': + type: string + format: uri-reference + Info: + type: object + required: + - title + - version + properties: + title: + type: string + description: + type: string + termsOfService: + type: string + format: uri-reference + contact: + $ref: '#/definitions/Contact' + license: + $ref: '#/definitions/License' + version: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + + Contact: + type: object + properties: + name: + type: string + url: + type: string + format: uri-reference + email: + type: string + format: email + patternProperties: + '^x-': {} + additionalProperties: false + + License: + type: object + required: + - name + properties: + name: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Server: + type: object + required: + - url + properties: + url: + type: string + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/definitions/ServerVariable' + patternProperties: + '^x-': {} + additionalProperties: false + + ServerVariable: + type: object + required: + - default + properties: + enum: + type: array + items: + type: string + default: + type: string + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Components: + type: object + properties: + schemas: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + responses: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Response' + parameters: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Parameter' + examples: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Example' + requestBodies: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/RequestBody' + headers: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Header' + securitySchemes: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/SecurityScheme' + links: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Link' + callbacks: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Callback' + patternProperties: + '^x-': {} + additionalProperties: false + + Schema: + type: object + properties: + title: + type: string + multipleOf: + type: number + minimum: 0 + exclusiveMinimum: true + maximum: + type: number + exclusiveMaximum: + type: boolean + default: false + minimum: + type: number + exclusiveMinimum: + type: boolean + default: false + maxLength: + type: integer + minimum: 0 + minLength: + type: integer + minimum: 0 + default: 0 + pattern: + type: string + format: regex + maxItems: + type: integer + minimum: 0 + minItems: + type: integer + minimum: 0 + default: 0 + uniqueItems: + type: boolean + default: false + maxProperties: + type: integer + minimum: 0 + minProperties: + type: integer + minimum: 0 + default: 0 + required: + type: array + items: + type: string + minItems: 1 + uniqueItems: true + enum: + type: array + items: {} + minItems: 1 + uniqueItems: false + type: + type: string + enum: + - array + - boolean + - integer + - number + - object + - string + not: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + allOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + oneOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + anyOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + properties: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + - type: boolean + default: true + description: + type: string + format: + type: string + default: {} + nullable: + type: boolean + default: false + discriminator: + $ref: '#/definitions/Discriminator' + readOnly: + type: boolean + default: false + writeOnly: + type: boolean + default: false + example: {} + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + deprecated: + type: boolean + default: false + xml: + $ref: '#/definitions/XML' + patternProperties: + '^x-': {} + additionalProperties: false + + Discriminator: + type: object + required: + - propertyName + properties: + propertyName: + type: string + mapping: + type: object + additionalProperties: + type: string + + XML: + type: object + properties: + name: + type: string + namespace: + type: string + format: uri + prefix: + type: string + attribute: + type: boolean + default: false + wrapped: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + Response: + type: object + required: + - description + properties: + description: + type: string + headers: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + links: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Link' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + + MediaType: + type: object + properties: + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + encoding: + type: object + additionalProperties: + $ref: '#/definitions/Encoding' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + + Example: + type: object + properties: + summary: + type: string + description: + type: string + value: {} + externalValue: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Header: + type: object + properties: + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + enum: + - simple + default: simple + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + + Paths: + type: object + patternProperties: + '^\/': + $ref: '#/definitions/PathItem' + '^x-': {} + additionalProperties: false + + PathItem: + type: object + properties: + $ref: + type: string + summary: + type: string + description: + type: string + servers: + type: array + items: + $ref: '#/definitions/Server' + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + patternProperties: + '^(get|put|post|delete|options|head|patch|trace)$': + $ref: '#/definitions/Operation' + '^x-': {} + additionalProperties: false + + Operation: + type: object + required: + - responses + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + operationId: + type: string + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + requestBody: + oneOf: + - $ref: '#/definitions/RequestBody' + - $ref: '#/definitions/Reference' + responses: + $ref: '#/definitions/Responses' + callbacks: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Callback' + - $ref: '#/definitions/Reference' + deprecated: + type: boolean + default: false + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + servers: + type: array + items: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + + Responses: + type: object + properties: + default: + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + patternProperties: + '^[1-5](?:\d{2}|XX)$': + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + '^x-': {} + minProperties: 1 + additionalProperties: false + + + SecurityRequirement: + type: object + additionalProperties: + type: array + items: + type: string + + Tag: + type: object + required: + - name + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + patternProperties: + '^x-': {} + additionalProperties: false + + ExternalDocumentation: + type: object + required: + - url + properties: + description: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + ExampleXORExamples: + description: Example and examples are mutually exclusive + not: + required: [example, examples] + + SchemaXORContent: + description: Schema and content are mutually exclusive, at least one is required + not: + required: [schema, content] + oneOf: + - required: [schema] + - required: [content] + description: Some properties are not allowed if content is present + allOf: + - not: + required: [style] + - not: + required: [explode] + - not: + required: [allowReserved] + - not: + required: [example] + - not: + required: [examples] + + Parameter: + type: object + properties: + name: + type: string + in: + type: string + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + required: + - name + - in + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + - $ref: '#/definitions/ParameterLocation' + + ParameterLocation: + description: Parameter location + oneOf: + - description: Parameter in path + required: + - required + properties: + in: + enum: [path] + style: + enum: [matrix, label, simple] + default: simple + required: + enum: [true] + + - description: Parameter in query + properties: + in: + enum: [query] + style: + enum: [form, spaceDelimited, pipeDelimited, deepObject] + default: form + + - description: Parameter in header + properties: + in: + enum: [header] + style: + enum: [simple] + default: simple + + - description: Parameter in cookie + properties: + in: + enum: [cookie] + style: + enum: [form] + default: form + + RequestBody: + type: object + required: + - content + properties: + description: + type: string + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + required: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + SecurityScheme: + oneOf: + - $ref: '#/definitions/APIKeySecurityScheme' + - $ref: '#/definitions/HTTPSecurityScheme' + - $ref: '#/definitions/OAuth2SecurityScheme' + - $ref: '#/definitions/OpenIdConnectSecurityScheme' + + APIKeySecurityScheme: + type: object + required: + - type + - name + - in + properties: + type: + type: string + enum: + - apiKey + name: + type: string + in: + type: string + enum: + - header + - query + - cookie + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + HTTPSecurityScheme: + type: object + required: + - scheme + - type + properties: + scheme: + type: string + bearerFormat: + type: string + description: + type: string + type: + type: string + enum: + - http + patternProperties: + '^x-': {} + additionalProperties: false + oneOf: + - description: Bearer + properties: + scheme: + enum: [bearer] + + - description: Non Bearer + not: + required: [bearerFormat] + properties: + scheme: + not: + enum: [bearer] + + OAuth2SecurityScheme: + type: object + required: + - type + - flows + properties: + type: + type: string + enum: + - oauth2 + flows: + $ref: '#/definitions/OAuthFlows' + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OpenIdConnectSecurityScheme: + type: object + required: + - type + - openIdConnectUrl + properties: + type: + type: string + enum: + - openIdConnect + openIdConnectUrl: + type: string + format: uri-reference + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OAuthFlows: + type: object + properties: + implicit: + $ref: '#/definitions/ImplicitOAuthFlow' + password: + $ref: '#/definitions/PasswordOAuthFlow' + clientCredentials: + $ref: '#/definitions/ClientCredentialsFlow' + authorizationCode: + $ref: '#/definitions/AuthorizationCodeOAuthFlow' + patternProperties: + '^x-': {} + additionalProperties: false + + ImplicitOAuthFlow: + type: object + required: + - authorizationUrl + - scopes + properties: + authorizationUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + PasswordOAuthFlow: + type: object + required: + - tokenUrl + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + ClientCredentialsFlow: + type: object + required: + - tokenUrl + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + AuthorizationCodeOAuthFlow: + type: object + required: + - authorizationUrl + - tokenUrl + properties: + authorizationUrl: + type: string + format: uri-reference + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Link: + type: object + properties: + operationId: + type: string + operationRef: + type: string + format: uri-reference + parameters: + type: object + additionalProperties: {} + requestBody: {} + description: + type: string + server: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + not: + description: Operation Id and Operation Ref are mutually exclusive + required: [operationId, operationRef] + + Callback: + type: object + additionalProperties: + $ref: '#/definitions/PathItem' + patternProperties: + '^x-': {} + + Encoding: + type: object + properties: + contentType: + type: string + headers: + type: object + additionalProperties: + $ref: '#/definitions/Header' + style: + type: string + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + type: boolean + default: false + additionalProperties: false diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md new file mode 100644 index 0000000000..01da62b56d --- /dev/null +++ b/schemas/v3.1/README.md @@ -0,0 +1,41 @@ +# OpenAPI 3.1.X JSON Schema + +Here you can find the JSON Schema for validating OpenAPI definitions of versions +3.1.X. + +As a reminder, the JSON Schema is not the source of truth for the Specification. +In cases of conflicts between the Specification itself and the JSON Schema, the +Specification wins. Also, some Specification constraints cannot be represented +with the JSON Schema so it's highly recommended to employ other methods to +ensure compliance. + +The iteration version of the JSON Schema can be found in the `$id` field. For +example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` +means this iteration was created on March 2nd, 2021. + +The `schema.yaml` schema doesn't validate the JSON Schemas in your OpenAPI +document because 3.1 allows you to use any JSON Schema dialect you choose. We +have also included `schema-base.yaml` that extends the main schema to validate +that all schemas use the default OAS base vocabulary. + +## Contributing +To submit improvements to the schema, modify the schema.yaml file only. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Convert the schema.yaml to schema.json +- Publish the new version + +## Tests +The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. + +```bash +npx mocha --recursive tests +``` + +You can also validate a document individually. + +```bash +scripts/validate.js path/to/document/to/validate.yaml +``` diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json new file mode 100644 index 0000000000..d54b0d4d7c --- /dev/null +++ b/schemas/v3.1/dialect/base.schema.json @@ -0,0 +1,21 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/dialect/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/core": true, + "https://json-schema.org/draft/2020-12/vocab/applicator": true, + "https://json-schema.org/draft/2020-12/vocab/unevaluated": true, + "https://json-schema.org/draft/2020-12/vocab/validation": true, + "https://json-schema.org/draft/2020-12/vocab/meta-data": true, + "https://json-schema.org/draft/2020-12/vocab/format-annotation": true, + "https://json-schema.org/draft/2020-12/vocab/content": true, + "https://spec.openapis.org/oas/3.1/vocab/base": false + }, + "$dynamicAnchor": "meta", + + "title": "OpenAPI 3.1 Schema Object Dialect", + "allOf": [ + { "$ref": "https://json-schema.org/draft/2020-12/schema" }, + { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } + ] +} diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json new file mode 100644 index 0000000000..f3ee03fb96 --- /dev/null +++ b/schemas/v3.1/meta/base.schema.json @@ -0,0 +1,79 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/meta/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://spec.openapis.org/oas/3.1/vocab/base": true + }, + "$dynamicAnchor": "meta", + "title": "OAS Base vocabulary", + + "type": ["object", "boolean"], + "properties": { + "example": true, + "discriminator": { "$ref": "#/$defs/discriminator" }, + "externalDocs": { "$ref": "#/$defs/external-docs" }, + "xml": { "$ref": "#/$defs/xml" } + }, + "$defs": { + "extensible": { + "patternProperties": { + "^x-": true + } + }, + "discriminator": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": ["propertyName"], + "unevaluatedProperties": false + }, + "external-docs": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "required": ["url"], + "unevaluatedProperties": false + }, + "xml": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean" + }, + "wrapped": { + "type": "boolean" + } + }, + "unevaluatedProperties": false + } + } +} diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json new file mode 100644 index 0000000000..658e943cc5 --- /dev/null +++ b/schemas/v3.1/schema-base.json @@ -0,0 +1,24 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-04-15", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", + "properties": { + "jsonSchemaDialect": { + "$ref": "#/$defs/dialect" + } + }, + "$defs": { + "dialect": { + "const": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "schema": { + "$dynamicAnchor": "meta", + "$ref\"": "https://spec.openapis.org/oas/3.1/dialect/base", + "properties": { + "$schema": { + "$ref": "#/$defs/dialect" + } + } + } + } +} diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml new file mode 100644 index 0000000000..515ed08989 --- /dev/null +++ b/schemas/v3.1/schema-base.yaml @@ -0,0 +1,17 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-04-15' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' +properties: + jsonSchemaDialect: + $ref: '#/$defs/dialect' + +$defs: + dialect: + const: 'https://spec.openapis.org/oas/3.1/dialect/base' + schema: + $dynamicAnchor: meta + $ref": 'https://spec.openapis.org/oas/3.1/dialect/base' + properties: + $schema: + $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json new file mode 100644 index 0000000000..a798834247 --- /dev/null +++ b/schemas/v3.1/schema.json @@ -0,0 +1,1343 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.1\\.\\d+(-.+)?$" + }, + "info": { + "$ref": "#/$defs/info" + }, + "jsonSchemaDialect": { + "$ref": "#/$defs/uri", + "default": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "paths": { + "$ref": "#/$defs/paths" + }, + "webhooks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "components": { + "$ref": "#/$defs/components" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/$defs/tag" + } + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "openapi", + "info" + ], + "anyOf": [ + { + "required": [ + "paths" + ] + }, + { + "required": [ + "components" + ] + }, + { + "required": [ + "webhooks" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "info": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string" + }, + "contact": { + "$ref": "#/$defs/contact" + }, + "license": { + "$ref": "#/$defs/license" + }, + "version": { + "type": "string" + } + }, + "required": [ + "title", + "version" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "license": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "identifier": { + "type": "string" + }, + "url": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "name" + ], + "oneOf": [ + { + "required": [ + "identifier" + ] + }, + { + "required": [ + "url" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server": { + "type": "object", + "properties": { + "url": { + "$ref": "#/$defs/uri" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/server-variable" + } + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server-variable": { + "type": "object", + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "default": { + "type": "string" + }, + "descriptions": { + "type": "string" + } + }, + "required": [ + "default" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "additionalProperties": { + "$dynamicRef": "#meta" + } + }, + "responses": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/response-or-reference" + } + }, + "parameters": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + }, + "requestBodies": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/request-body-or-reference" + } + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "securitySchemes": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/security-scheme-or-reference" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "pathItems": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + } + }, + "patternProperties": { + "^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$": { + "$comment": "Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected", + "propertyNames": { + "pattern": "^[a-zA-Z0-9._-]+$" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "paths": { + "type": "object", + "patternProperties": { + "^/": { + "$ref": "#/$defs/path-item" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + } + } + }, + "patternProperties": { + "^(get|put|post|delete|options|head|patch|trace)$": { + "$ref": "#/$defs/operation" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/path-item" + } + }, + "operation": { + "type": "object", + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "requestBody": { + "$ref": "#/$defs/request-body-or-reference" + }, + "responses": { + "$ref": "#/$defs/responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "external-documentation": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "url": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "path", + "cookie" + ] + }, + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "$ref": "#/$defs/content" + } + }, + "required": [ + "in" + ], + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form" + } + ], + "$defs": { + "styles-for-path": { + "if": { + "properties": { + "in": { + "const": "path" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "matrix", + "label", + "simple" + ] + }, + "required": { + "const": true + } + }, + "required": [ + "required" + ] + } + }, + "styles-for-header": { + "if": { + "properties": { + "in": { + "const": "header" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + } + } + } + }, + "styles-for-query": { + "if": { + "properties": { + "in": { + "const": "query" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + } + } + } + }, + "styles-for-cookie": { + "if": { + "properties": { + "in": { + "const": "cookie" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form" + ] + } + } + } + }, + "styles-for-form": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/parameter" + } + }, + "request-body": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "content": { + "$ref": "#/$defs/content" + }, + "required": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "content" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "request-body-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/request-body" + } + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + }, + "propertyNames": { + "format": "media-range" + } + }, + "media-type": { + "type": "object", + "properties": { + "schema": { + "$dynamicRef": "#meta" + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/encoding" + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/examples" + } + ], + "unevaluatedProperties": false + }, + "encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string", + "format": "media-range" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/encoding/$defs/explode-default" + } + ], + "unevaluatedProperties": false, + "$defs": { + "explode-default": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + }, + "responses": { + "type": "object", + "properties": { + "default": { + "$ref": "#/$defs/response-or-reference" + } + }, + "patternProperties": { + "^[1-5][0-9X]{2}$": { + "$ref": "#/$defs/response-or-reference" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "content": { + "$ref": "#/$defs/content" + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + } + }, + "required": [ + "description" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/response" + } + }, + "callbacks": { + "type": "object", + "$ref": "#/$defs/specification-extensions", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "callbacks-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/callbacks" + } + }, + "example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": true, + "externalValue": { + "$ref": "#/$defs/uri" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "example-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/example" + } + }, + "link": { + "type": "object", + "properties": { + "operationRef": { + "$ref": "#/$defs/uri" + }, + "operationId": true, + "parameters": { + "$ref": "#/$defs/map-of-strings" + }, + "requestBody": true, + "description": { + "type": "string" + }, + "body": { + "$ref": "#/$defs/server" + } + }, + "oneOf": [ + { + "required": [ + "operationRef" + ] + }, + { + "required": [ + "operationId" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "link-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/link" + } + }, + "header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + }, + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + }, + "explode": { + "default": false, + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + } + }, + "$ref": "#/$defs/examples" + }, + "content": { + "properties": { + "content": { + "$ref": "#/$defs/content" + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "header-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/header" + } + }, + "tag": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "name" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "reference": { + "type": "object", + "properties": { + "$ref": { + "$ref": "#/$defs/uri" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "unevaluatedProperties": false + }, + "schema": { + "$dynamicAnchor": "meta", + "type": [ + "object", + "boolean" + ] + }, + "security-scheme": { + "type": "object", + "properties": { + "type": { + "enum": [ + "apiKey", + "http", + "mutualTLS", + "oauth2", + "openIdConnect" + ] + }, + "description": { + "type": "string" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-apikey" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http-bearer" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oauth2" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oidc" + } + ], + "unevaluatedProperties": false, + "$defs": { + "type-apikey": { + "if": { + "properties": { + "type": { + "const": "apiKey" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "cookie" + ] + } + }, + "required": [ + "name", + "in" + ] + } + }, + "type-http": { + "if": { + "properties": { + "type": { + "const": "http" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "scheme": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-http-bearer": { + "if": { + "properties": { + "type": { + "const": "http" + }, + "scheme": { + "const": "bearer" + } + }, + "required": [ + "type", + "scheme" + ] + }, + "then": { + "properties": { + "bearerFormat": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-oauth2": { + "if": { + "properties": { + "type": { + "const": "oauth2" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "flows": { + "$ref": "#/$defs/oauth-flows" + } + }, + "required": [ + "flows" + ] + } + }, + "type-oidc": { + "if": { + "properties": { + "type": { + "const": "openIdConnect" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "openIdConnectUrl": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "openIdConnectUrl" + ] + } + } + } + }, + "security-scheme-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/security-scheme" + } + }, + "oauth-flows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/$defs/oauth-flows/$defs/implicit" + }, + "password": { + "$ref": "#/$defs/oauth-flows/$defs/password" + }, + "clientCredentials": { + "$ref": "#/$defs/oauth-flows/$defs/client-credentials" + }, + "authorizationCode": { + "$ref": "#/$defs/oauth-flows/$defs/authorization-code" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "implicit": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "password": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "client-credentials": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "authorization-code": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + } + } + }, + "security-requirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "specification-extensions": { + "patternProperties": { + "^x-": true + } + }, + "examples": { + "properties": { + "example": true, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + } + } + }, + "uri": { + "type": "string", + "format": "uri" + }, + "map-of-strings": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } +} diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml new file mode 100644 index 0000000000..86cb44efca --- /dev/null +++ b/schemas/v3.1/schema.yaml @@ -0,0 +1,913 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +type: object +properties: + openapi: + type: string + pattern: '^3\.1\.\d+(-.+)?$' + info: + $ref: '#/$defs/info' + jsonSchemaDialect: + $ref: '#/$defs/uri' + default: 'https://spec.openapis.org/oas/3.1/dialect/base' + servers: + type: array + items: + $ref: '#/$defs/server' + paths: + $ref: '#/$defs/paths' + webhooks: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + components: + $ref: '#/$defs/components' + security: + type: array + items: + $ref: '#/$defs/security-requirement' + tags: + type: array + items: + $ref: '#/$defs/tag' + externalDocs: + $ref: '#/$defs/external-documentation' +required: + - openapi + - info +anyOf: + - required: + - paths + - required: + - components + - required: + - webhooks +$ref: '#/$defs/specification-extensions' +unevaluatedProperties: false + +$defs: + info: + type: object + properties: + title: + type: string + summary: + type: string + description: + type: string + termsOfService: + type: string + contact: + $ref: '#/$defs/contact' + license: + $ref: '#/$defs/license' + version: + type: string + required: + - title + - version + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + contact: + type: object + properties: + name: + type: string + url: + type: string + email: + type: string + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + license: + type: object + properties: + name: + type: string + identifier: + type: string + url: + $ref: '#/$defs/uri' + required: + - name + oneOf: + - required: + - identifier + - required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server: + type: object + properties: + url: + $ref: '#/$defs/uri' + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/$defs/server-variable' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server-variable: + type: object + properties: + enum: + type: array + items: + type: string + minItems: 1 + default: + type: string + descriptions: + type: string + required: + - default + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + components: + type: object + properties: + schemas: + type: object + additionalProperties: + $dynamicRef: '#meta' + responses: + type: object + additionalProperties: + $ref: '#/$defs/response-or-reference' + parameters: + type: object + additionalProperties: + $ref: '#/$defs/parameter-or-reference' + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + requestBodies: + type: object + additionalProperties: + $ref: '#/$defs/request-body-or-reference' + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + securitySchemes: + type: object + additionalProperties: + $ref: '#/$defs/security-scheme-or-reference' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + pathItems: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + patternProperties: + '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': + $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected + propertyNames: + pattern: '^[a-zA-Z0-9._-]+$' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + paths: + type: object + patternProperties: + '^/': + $ref: '#/$defs/path-item' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item: + type: object + properties: + summary: + type: string + description: + type: string + servers: + type: array + items: + $ref: '#/$defs/server' + parameters: + type: array + items: + $ref: '#/$defs/parameter-or-reference' + patternProperties: + '^(get|put|post|delete|options|head|patch|trace)$': + $ref: '#/$defs/operation' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/path-item' + + operation: + type: object + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + operationId: + type: string + parameters: + type: array + items: + $ref: '#/$defs/parameter-or-reference' + requestBody: + $ref: '#/$defs/request-body-or-reference' + responses: + $ref: '#/$defs/responses' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + deprecated: + default: false + type: boolean + security: + type: array + items: + $ref: '#/$defs/security-requirement' + servers: + type: array + items: + $ref: '#/$defs/server' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + external-documentation: + type: object + properties: + description: + type: string + url: + $ref: '#/$defs/uri' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter: + type: object + properties: + name: + type: string + in: + enum: + - query + - header + - path + - cookie + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + schema: + $dynamicRef: '#meta' + content: + $ref: '#/$defs/content' + required: + - in + oneOf: + - required: + - schema + - required: + - content + dependentSchemas: + schema: + properties: + style: + type: string + explode: + type: boolean + allowReserved: + default: false + type: boolean + allOf: + - $ref: '#/$defs/examples' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form' + + $defs: + styles-for-path: + if: + properties: + in: + const: path + required: + - in + then: + properties: + style: + default: simple + enum: + - matrix + - label + - simple + required: + const: true + required: + - required + + styles-for-header: + if: + properties: + in: + const: header + required: + - in + then: + properties: + style: + default: simple + enum: + - simple + + styles-for-query: + if: + properties: + in: + const: query + required: + - in + then: + properties: + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + + styles-for-cookie: + if: + properties: + in: + const: cookie + required: + - in + then: + properties: + style: + default: form + enum: + - form + + styles-for-form: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/parameter' + + request-body: + type: object + properties: + description: + type: string + content: + $ref: '#/$defs/content' + required: + default: false + type: boolean + required: + - content + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + request-body-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/request-body' + + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + propertyNames: + format: media-range + + media-type: + type: object + properties: + schema: + $dynamicRef: '#meta' + encoding: + type: object + additionalProperties: + $ref: '#/$defs/encoding' + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/examples' + unevaluatedProperties: false + + encoding: + type: object + properties: + contentType: + type: string + format: media-range + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + default: false + type: boolean + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/encoding/$defs/explode-default' + unevaluatedProperties: false + + $defs: + explode-default: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + responses: + type: object + properties: + default: + $ref: '#/$defs/response-or-reference' + patternProperties: + '^[1-5][0-9X]{2}$': + $ref: '#/$defs/response-or-reference' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response: + type: object + properties: + description: + type: string + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + content: + $ref: '#/$defs/content' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + required: + - description + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/response' + + callbacks: + type: object + $ref: '#/$defs/specification-extensions' + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + + callbacks-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/callbacks' + + example: + type: object + properties: + summary: + type: string + description: + type: string + value: true + externalValue: + $ref: '#/$defs/uri' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + example-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/example' + + link: + type: object + properties: + operationRef: + $ref: '#/$defs/uri' + operationId: true + parameters: + $ref: '#/$defs/map-of-strings' + requestBody: true + description: + type: string + body: + $ref: '#/$defs/server' + oneOf: + - required: + - operationRef + - required: + - operationId + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + link-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/link' + + header: + type: object + properties: + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + dependentSchemas: + schema: + properties: + style: + default: simple + enum: + - simple + explode: + default: false + type: boolean + allowReserved: + default: false + type: boolean + schema: + $dynamicRef: '#meta' + $ref: '#/$defs/examples' + content: + properties: + content: + $ref: '#/$defs/content' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + header-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/header' + + tag: + type: object + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + required: + - name + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + reference: + type: object + properties: + $ref: + $ref: '#/$defs/uri' + summary: + type: string + description: + type: string + unevaluatedProperties: false + + schema: + $dynamicAnchor: meta + type: + - object + - boolean + + security-scheme: + type: object + properties: + type: + enum: + - apiKey + - http + - mutualTLS + - oauth2 + - openIdConnect + description: + type: string + required: + - type + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/security-scheme/$defs/type-apikey' + - $ref: '#/$defs/security-scheme/$defs/type-http' + - $ref: '#/$defs/security-scheme/$defs/type-http-bearer' + - $ref: '#/$defs/security-scheme/$defs/type-oauth2' + - $ref: '#/$defs/security-scheme/$defs/type-oidc' + unevaluatedProperties: false + + $defs: + type-apikey: + if: + properties: + type: + const: apiKey + required: + - type + then: + properties: + name: + type: string + in: + enum: + - query + - header + - cookie + required: + - name + - in + + type-http: + if: + properties: + type: + const: http + required: + - type + then: + properties: + scheme: + type: string + required: + - scheme + + type-http-bearer: + if: + properties: + type: + const: http + scheme: + const: bearer + required: + - type + - scheme + then: + properties: + bearerFormat: + type: string + required: + - scheme + + type-oauth2: + if: + properties: + type: + const: oauth2 + required: + - type + then: + properties: + flows: + $ref: '#/$defs/oauth-flows' + required: + - flows + + type-oidc: + if: + properties: + type: + const: openIdConnect + required: + - type + then: + properties: + openIdConnectUrl: + $ref: '#/$defs/uri' + required: + - openIdConnectUrl + + security-scheme-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/security-scheme' + + oauth-flows: + type: object + properties: + implicit: + $ref: '#/$defs/oauth-flows/$defs/implicit' + password: + $ref: '#/$defs/oauth-flows/$defs/password' + clientCredentials: + $ref: '#/$defs/oauth-flows/$defs/client-credentials' + authorizationCode: + $ref: '#/$defs/oauth-flows/$defs/authorization-code' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + $defs: + implicit: + type: object + properties: + authorizationUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + password: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + client-credentials: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + authorization-code: + type: object + properties: + authorizationUrl: + type: string + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + security-requirement: + type: object + additionalProperties: + type: array + items: + type: string + + specification-extensions: + patternProperties: + '^x-': true + + examples: + properties: + example: true + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + + uri: + type: string + format: uri + + map-of-strings: + type: object + additionalProperties: + type: string diff --git a/scripts/validate.js b/scripts/validate.js new file mode 100755 index 0000000000..c9c70db797 --- /dev/null +++ b/scripts/validate.js @@ -0,0 +1,58 @@ +#!/usr/bin/env node + +const fs = require("fs"); +const yaml = require("yaml"); +const JsonSchema = require("@hyperjump/json-schema"); +const dialect = require("../schemas/v3.1/dialect/base.schema.json"); +const vocabulary = require("../schemas/v3.1/meta/base.schema.json"); + + +if (process.argv.length < 3) { + console.log("Usage: validate [--schema=schema] [--version=2021-03-02] [--format=BASIC] path-to-file.yaml"); + console.log("\t--schema: (Default: schema) The name of the yaml schema file to use"); + console.log("\t--version: (Default: 2021-03-02) The version of the yaml schema file to use"); + console.log("\t--format: (Default: BASIC) The JSON Schema output format to use. Options: FLAG, BASIC, DETAILED, VERBOSE"); + process.exit(1); +} + +const args = process.argv.reduce((acc, arg) => { + if (!arg.startsWith("--")) return acc; + + const [argName, argValue] = arg.substring(2).split("=", 2); + return { ...acc, [argName]: argValue }; +}, {}); + +(async function () { + try { + const schemaType = args.schema || "schema"; + const schemaVersion = args.version || "2021-03-02"; + const outputFormat = args.format || JsonSchema.BASIC; + + // Config + JsonSchema.setMetaOutputFormat(outputFormat); + //JsonSchema.setShouldMetaValidate(false); + + // Load schemas + JsonSchema.add(dialect); + JsonSchema.add(vocabulary); + fs.readdirSync(`${__dirname}/../schemas/v3.1`, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .map((entry) => fs.readFileSync(`${__dirname}/../schemas/v3.1/${entry.name}`, "utf8")) + .map((schemaYaml) => yaml.parse(schemaYaml)) + .forEach((schema) => JsonSchema.add(schema)); + + // Compile / meta-validate + const schema = await JsonSchema.get(`https://spec.openapis.org/oas/3.1/${schemaType}/${schemaVersion}`); + const validateSchema = await JsonSchema.validate(schema); + + // Validate instance + const instanceYaml = fs.readFileSync(`${process.cwd()}/${process.argv[process.argv.length - 1]}`, "utf8"); + const instance = yaml.parse(instanceYaml); + const results = validateSchema(instance, outputFormat); + console.log(JSON.stringify(results, null, " ")); + } catch (error) { + console.log("************* Error ***************"); + console.log(error); + console.log(JSON.stringify(error.output, null, " ")); + } +}()); diff --git a/scripts/yaml2json/yaml2json.js b/scripts/yaml2json/yaml2json.js new file mode 100755 index 0000000000..f69145ad36 --- /dev/null +++ b/scripts/yaml2json/yaml2json.js @@ -0,0 +1,30 @@ +#!/usr/bin/env node + +'use strict'; + +const fs = require('fs'); +const yaml = require('yaml'); + +function convert(filename) { + console.log(filename); + const s = fs.readFileSync(filename,'utf8'); + let obj; + try { + obj = yaml.parse(s, {prettyErrors: true}); + fs.writeFileSync(filename.replace('.yaml','.json'),JSON.stringify(obj,null,2),'utf8'); + } + catch (ex) { + console.warn(' ',ex.message); + process.exitCode = 1; + } +} + +if (process.argv.length<3) { + console.warn('Usage: yaml2json {infiles}'); +} +else { + for (let i=2;i {
+ JsonSchema.add(dialect);
+ JsonSchema.add(vocabulary);
+ JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/../../schemas/v3.1/schema.yaml`, "utf8"), { prettyErrors: true }));
+ metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02");
+});
+
+describe("Pass", () => {
+ fs.readdirSync(`${__dirname}/pass`, { withFileTypes: true })
+ .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name))
+ .forEach((entry) => {
+ const file = `${__dirname}/pass/${entry.name}`;
+
+ it(entry.name, async () => {
+ const instance = yaml.parse(fs.readFileSync(file, "utf8"));
+
+ const output = await JsonSchema.validate(metaSchema, instance, JsonSchema.BASIC);
+ expect(output.valid).to.equal(true);
+ });
+ });
+});
+
+describe("Fail", () => {
+ fs.readdirSync(`${__dirname}/fail`, { withFileTypes: true })
+ .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name))
+ .forEach((entry) => {
+ const file = `${__dirname}/fail/${entry.name}`;
+
+ it(entry.name, async () => {
+ const instance = yaml.parse(fs.readFileSync(file, "utf8"));
+
+ const output = await JsonSchema.validate(metaSchema, instance);
+ expect(output.valid).to.equal(false);
+ });
+ });
+});
diff --git a/versions/3.0.1.md b/versions/3.0.1.md
new file mode 100644
index 0000000000..0a8a834358
--- /dev/null
+++ b/versions/3.0.1.md
@@ -0,0 +1,3380 @@
+# OpenAPI Specification
+
+#### Version 3.0.1
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+## Introduction
+
+The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
+
+## Table of Contents
+
+
+- [Definitions](#definitions)
+ - [OpenAPI Document](#oasDocument)
+ - [Path Templating](#pathTemplating)
+ - [Media Types](#mediaTypes)
+ - [HTTP Status Codes](#httpCodes)
+- [Specification](#specification)
+ - [Versions](#versions)
+ - [Format](#format)
+ - [Document Structure](#documentStructure)
+ - [Data Types](#dataTypes)
+ - [Rich Text Formatting](#richText)
+ - [Relative References In URLs](#relativeReferences)
+ - [Schema](#schema)
+ - [OpenAPI Object](#oasObject)
+ - [Info Object](#infoObject)
+ - [Contact Object](#contactObject)
+ - [License Object](#licenseObject)
+ - [Server Object](#serverObject)
+ - [Server Variable Object](#serverVariableObject)
+ - [Components Object](#componentsObject)
+ - [Paths Object](#pathsObject)
+ - [Path Item Object](#pathItemObject)
+ - [Operation Object](#operationObject)
+ - [External Documentation Object](#externalDocumentationObject)
+ - [Parameter Object](#parameterObject)
+ - [Request Body Object](#requestBodyObject)
+ - [Media Type Object](#mediaTypeObject)
+ - [Encoding Object](#encodingObject)
+ - [Responses Object](#responsesObject)
+ - [Response Object](#responseObject)
+ - [Callback Object](#callbackObject)
+ - [Example Object](#exampleObject)
+ - [Link Object](#linkObject)
+ - [Header Object](#headerObject)
+ - [Tag Object](#tagObject)
+ - [Reference Object](#referenceObject)
+ - [Schema Object](#schemaObject)
+ - [Discriminator Object](#discriminatorObject)
+ - [XML Object](#xmlObject)
+ - [Security Scheme Object](#securitySchemeObject)
+ - [OAuth Flows Object](#oauthFlowsObject)
+ - [OAuth Flow Object](#oauthFlowObject)
+ - [Security Requirement Object](#securityRequirementObject)
+ - [Specification Extensions](#specificationExtensions)
+ - [Security Filtering](#securityFiltering)
+- [Appendix A: Revision History](#revisionHistory)
+
+
+
+
+## Definitions
+
+##### OpenAPI Document
+A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
+
+##### Path Templating
+Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
+
+##### Media Types
+Media type definitions are spread across several resources.
+The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838).
+
+Some examples of possible media type definitions:
+```
+ text/plain; charset=utf-8
+ application/json
+ application/vnd.github+json
+ application/vnd.github.v3+json
+ application/vnd.github.v3.raw+json
+ application/vnd.github.v3.text+json
+ application/vnd.github.v3.html+json
+ application/vnd.github.v3.full+json
+ application/vnd.github.v3.diff
+ application/vnd.github.v3.patch
+```
+##### HTTP Status Codes
+The HTTP Status Codes are used to indicate the status of the executed operation.
+The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+
+## Specification
+
+### Versions
+
+The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+
+The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
+
+Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
+
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)
+
+### Format
+
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+
+For example, if a field has an array value, the JSON array representation will be used:
+
+```json
+{
+ "field": [ 1, 2, 3 ]
+}
+```
+All field names in the specification are **case sensitive**.
+
+The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+
+Patterned fields MUST have unique names within the containing object.
+
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
+
+- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346).
+
+**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
+
+### Document Structure
+
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions.
+
+It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
+
+### Data Types
+
+Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
+Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
+`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
+Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00.
+
+Primitives have an optional modifier property: `format`.
+OAS uses several known formats to define in fine detail the data type being used.
+However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
+Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
+
+The formats defined by the OAS are:
+
+Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
+----------- | ------ | -------- | --------
+integer | `integer` | `int32` | signed 32 bits
+long | `integer` | `int64` | signed 64 bits
+float | `number` | `float` | |
+double | `number` | `double` | |
+string | `string` | | |
+byte | `string` | `byte` | base64 encoded characters
+binary | `string` | `binary` | any sequence of octets
+boolean | `boolean` | | |
+date | `string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+password | `string` | `password` | A hint to UIs to obscure input.
+
+### Rich Text Formatting
+Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
+
+### Relative References in URLs
+
+Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
+
+Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
+
+### Schema
+
+In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
+
+#### OpenAPI Object
+
+This is the root document object of the [OpenAPI document](#oasDocument).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
+info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
+paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
+components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
+tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Info Object
+
+The object provides metadata about the API.
+The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+title | `string` | **REQUIRED**. The title of the application.
+description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
+contact | [Contact Object](#contactObject) | The contact information for the exposed API.
+license | [License Object](#licenseObject) | The license information for the exposed API.
+version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Info Object Example:
+
+```json
+{
+ "title": "Sample Pet Store App",
+ "description": "This is a sample server for a pet store.",
+ "termsOfService": "http://example.com/terms/",
+ "contact": {
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+ },
+ "version": "1.0.1"
+}
+```
+
+```yaml
+title: Sample Pet Store App
+description: This is a sample server for a pet store.
+termsOfService: http://example.com/terms/
+contact:
+ name: API Support
+ url: http://www.example.com/support
+ email: support@example.com
+license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+version: 1.0.1
+```
+
+#### Contact Object
+
+Contact information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | The identifying name of the contact person/organization.
+url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
+email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Contact Object Example:
+
+```json
+{
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+}
+```
+
+```yaml
+name: API Support
+url: http://www.example.com/support
+email: support@example.com
+```
+
+#### License Object
+
+License information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The license name used for the API.
+url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### License Object Example:
+
+```json
+{
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+}
+```
+
+```yaml
+name: Apache 2.0
+url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+#### Server Object
+
+An object representing a Server.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Server Object Example
+
+A single server would be described as:
+
+```json
+{
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+}
+```
+
+```yaml
+url: https://development.gigantic-server.com/v1
+description: Development server
+```
+
+The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+ },
+ {
+ "url": "https://staging.gigantic-server.com/v1",
+ "description": "Staging server"
+ },
+ {
+ "url": "https://api.gigantic-server.com/v1",
+ "description": "Production server"
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+ description: Development server
+- url: https://staging.gigantic-server.com/v1
+ description: Staging server
+- url: https://api.gigantic-server.com/v1
+ description: Production server
+```
+
+The following shows how variables can be used for a server configuration:
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
+ "description": "The production API server",
+ "variables": {
+ "username": {
+ "default": "demo",
+ "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+ },
+ "port": {
+ "enum": [
+ "8443",
+ "443"
+ ],
+ "default": "8443"
+ },
+ "basePath": {
+ "default": "v2"
+ }
+ }
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+ description: The production API server
+ variables:
+ username:
+ # note! no enum here means it is an open value
+ default: demo
+ description: this value is assigned by the service provider, in this example `gigantic-server.com`
+ port:
+ enum:
+ - '8443'
+ - '443'
+ default: '8443'
+ basePath:
+ # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+ default: v2
+```
+
+
+#### Server Variable Object
+
+An object representing a Server Variable for server URL template substitution.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set.
+default | `string` | **REQUIRED**. The default value to use for substitution, and to send, if an alternate value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
+description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Components Object
+
+Holds a set of reusable objects for different aspects of the OAS.
+All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+ schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+ responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
+ parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
+ examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
+ requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
+ headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
+ securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
+ links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
+ callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+
+Field Name Examples:
+
+```
+User
+User_1
+User_Name
+user-name
+my.org.User
+```
+
+##### Components Object Example
+
+```json
+"components": {
+ "schemas": {
+ "Category": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "Tag": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "parameters": {
+ "skipParam": {
+ "name": "skip",
+ "in": "query",
+ "description": "number of items to skip",
+ "required": true,
+ "schema": {
+ "type": "integer",
+ "format": "int32"
+ }
+ },
+ "limitParam": {
+ "name": "limit",
+ "in": "query",
+ "description": "max records to return",
+ "required": true,
+ "schema" : {
+ "type": "integer",
+ "format": "int32"
+ }
+ }
+ },
+ "responses": {
+ "NotFound": {
+ "description": "Entity not found."
+ },
+ "IllegalInput": {
+ "description": "Illegal input for operation."
+ },
+ "GeneralError": {
+ "description": "General Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GeneralError"
+ }
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "http://example.org/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+components:
+ schemas:
+ Category:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ Tag:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ parameters:
+ skipParam:
+ name: skip
+ in: query
+ description: number of items to skip
+ required: true
+ schema:
+ type: integer
+ format: int32
+ limitParam:
+ name: limit
+ in: query
+ description: max records to return
+ required: true
+ schema:
+ type: integer
+ format: int32
+ responses:
+ NotFound:
+ description: Entity not found.
+ IllegalInput:
+ description: Illegal input for operation.
+ GeneralError:
+ description: General Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GeneralError'
+ securitySchemes:
+ api_key:
+ type: apiKey
+ name: api_key
+ in: header
+ petstore_auth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: http://example.org/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+
+#### Paths Object
+
+Holds the relative paths to the individual endpoints and their operations.
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+ /pets/{petId}
+ /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+ /pets/{petId}
+ /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+ /{entity}/me
+ /books/{id}
+```
+
+##### Paths Object Example
+
+```json
+{
+ "/pets": {
+ "get": {
+ "description": "Returns all pets from the system that the user has access to",
+ "responses": {
+ "200": {
+ "description": "A list of pets.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/pet"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+/pets:
+ get:
+ description: Returns all pets from the system that the user has access to
+ responses:
+ '200':
+ description: A list of pets.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/pet'
+```
+
+#### Path Item Object
+
+Describes the operations available on a single path.
+A Path Item MAY be empty, due to [ACL constraints](#securityFiltering).
+The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*.
+summary| `string` | An optional, string summary, intended to apply to all operations in this path.
+description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
+put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
+post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
+delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
+options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
+head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
+patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
+trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Item Object Example
+
+```json
+{
+ "get": {
+ "description": "Returns pets based on ID",
+ "summary": "Find pets by ID",
+ "operationId": "getPetsById",
+ "responses": {
+ "200": {
+ "description": "pet response",
+ "content": {
+ "*/*": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Pet"
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "error payload",
+ "content": {
+ "text/html": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorModel"
+ }
+ }
+ }
+ }
+ }
+ },
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "description": "ID of pet to use",
+ "required": true,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "style": "simple"
+ }
+ ]
+}
+```
+
+```yaml
+get:
+ description: Returns pets based on ID
+ summary: Find pets by ID
+ operationId: getPetsById
+ responses:
+ '200':
+ description: pet response
+ content:
+ '*/*' :
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Pet'
+ default:
+ description: error payload
+ content:
+ 'text/html':
+ schema:
+ $ref: '#/components/schemas/ErrorModel'
+parameters:
+- name: id
+ in: path
+ description: ID of pet to use
+ required: true
+ schema:
+ type: array
+ style: simple
+ items:
+ type: string
+```
+
+#### Operation Object
+
+Describes a single API operation on a path.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
+summary | `string` | A short summary of what the operation does.
+description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
+operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
+responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation.
+callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Operation Object Example
+
+```json
+{
+ "tags": [
+ "pet"
+ ],
+ "summary": "Updates a pet in the store with form data",
+ "operationId": "updatePetWithForm",
+ "parameters": [
+ {
+ "name": "petId",
+ "in": "path",
+ "description": "ID of pet that needs to be updated",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "description": "Updated name of the pet",
+ "type": "string"
+ },
+ "status": {
+ "description": "Updated status of the pet",
+ "type": "string"
+ }
+ },
+ "required": ["status"]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Pet updated.",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ },
+ "405": {
+ "description": "Invalid input",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ }
+ },
+ "security": [
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+tags:
+- pet
+summary: Updates a pet in the store with form data
+operationId: updatePetWithForm
+parameters:
+- name: petId
+ in: path
+ description: ID of pet that needs to be updated
+ required: true
+ schema:
+ type: string
+requestBody:
+ content:
+ 'application/x-www-form-urlencoded':
+ schema:
+ properties:
+ name:
+ description: Updated name of the pet
+ type: string
+ status:
+ description: Updated status of the pet
+ type: string
+ required:
+ - status
+responses:
+ '200':
+ description: Pet updated.
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+ '405':
+ description: Invalid input
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+security:
+- petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+
+#### External Documentation Object
+
+Allows referencing an external resource for extended documentation.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### External Documentation Object Example
+
+```json
+{
+ "description": "Find more info here",
+ "url": "https://example.com"
+}
+```
+
+```yaml
+description: Find more info here
+url: https://example.com
+```
+
+#### Parameter Object
+
+Describes a single operation parameter.
+
+A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
+
+##### Parameter Locations
+There are four possible parameter locations specified by the `in` field:
+* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
+* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* cookie - Used to pass a specific cookie value to the API.
+
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. ...
+```
+
+Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default):
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+```
+
+```xml
+...
+...
+...
+```
+
+###### XML Name Replacement
+
+```json
+{
+ "animals": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+...
+```
+
+
+###### XML Attribute, Prefix and Namespace
+
+In this example, a full model definition is shown.
+
+```json
+{
+ "Person": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int32",
+ "xml": {
+ "attribute": true
+ }
+ },
+ "name": {
+ "type": "string",
+ "xml": {
+ "namespace": "http://example.com/schema/sample",
+ "prefix": "sample"
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+Person:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int32
+ xml:
+ attribute: true
+ name:
+ type: string
+ xml:
+ namespace: http://example.com/schema/sample
+ prefix: sample
+```
+
+```xml
+
+ example
+
+```
+
+###### XML Arrays
+
+Changing the element names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+value
+value
+```
+
+The external `name` property has no effect on the XML:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+```
+
+```xml
+value
+value
+```
+
+Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+To overcome the naming problem in the example above, the following definition can be used:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+Affecting both internal and external names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+If we change the external element but not the internal ones:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+#### Security Scheme Object
+
+Defines a security scheme that can be used by the operations.
+Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
+description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
+in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
+scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).
+bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
+openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Security Scheme Object Example
+
+###### Basic Authentication Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "basic"
+}
+```
+
+```yaml
+type: http
+scheme: basic
+```
+
+###### API Key Sample
+
+```json
+{
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+}
+```
+
+```yaml
+type: apiKey
+name: api_key
+in: header
+```
+
+###### JWT Bearer Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "JWT",
+}
+```
+
+```yaml
+type: http
+scheme: bearer
+bearerFormat: JWT
+```
+
+###### Implicit OAuth2 Sample
+
+```json
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow
+password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow
+clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
+authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL.
+tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL.
+refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### OAuth Flow Object Examples
+
+```JSON
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "tokenUrl": "https://example.com/api/oauth/token",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```YAML
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+ authorizationCode:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ tokenUrl: https://example.com/api/oauth/token
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+
+#### Security Requirement Object
+
+Lists the required security schemes to execute this operation.
+The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject).
+
+Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
+This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
+
+When a list of Security Requirement Objects is defined on the [Open API object](#oasObject) or [Operation Object](#operationObject), only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.
+
+##### Security Requirement Object Examples
+
+###### Non-OAuth2 Security Requirement
+
+```json
+{
+ "api_key": []
+}
+```
+
+```yaml
+api_key: []
+```
+
+###### OAuth2 Security Requirement
+
+```json
+{
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+}
+```
+
+```yaml
+petstore_auth:
+- write:pets
+- read:pets
+```
+
+### Specification Extensions
+
+While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
+
+The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+
+Field Pattern | Type | Description
+---|:---:|---
+^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value.
+
+The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
+
+### Security Filtering
+
+Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.
+
+The reasoning is to allow an additional layer of access control over the documentation.
+While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.
+
+Two examples of this:
+
+1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
+2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
+
+## Appendix A: Revision History
+
+Version | Date | Notes
+--- | --- | ---
+3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
+3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
+3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
+3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification
+3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification
+2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative
+2.0 | 2014-09-08 | Release of Swagger 2.0
+1.2 | 2014-03-14 | Initial release of the formal document.
+1.1 | 2012-08-22 | Release of Swagger 1.1
+1.0 | 2011-08-10 | First release of the Swagger Specification
diff --git a/versions/3.0.2.md b/versions/3.0.2.md
new file mode 100644
index 0000000000..3a6a343a8c
--- /dev/null
+++ b/versions/3.0.2.md
@@ -0,0 +1,3412 @@
+# OpenAPI Specification
+
+#### Version 3.0.2
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+## Introduction
+
+The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
+
+## Table of Contents
+
+
+- [Definitions](#definitions)
+ - [OpenAPI Document](#oasDocument)
+ - [Path Templating](#pathTemplating)
+ - [Media Types](#mediaTypes)
+ - [HTTP Status Codes](#httpCodes)
+- [Specification](#specification)
+ - [Versions](#versions)
+ - [Format](#format)
+ - [Document Structure](#documentStructure)
+ - [Data Types](#dataTypes)
+ - [Rich Text Formatting](#richText)
+ - [Relative References In URLs](#relativeReferences)
+ - [Schema](#schema)
+ - [OpenAPI Object](#oasObject)
+ - [Info Object](#infoObject)
+ - [Contact Object](#contactObject)
+ - [License Object](#licenseObject)
+ - [Server Object](#serverObject)
+ - [Server Variable Object](#serverVariableObject)
+ - [Components Object](#componentsObject)
+ - [Paths Object](#pathsObject)
+ - [Path Item Object](#pathItemObject)
+ - [Operation Object](#operationObject)
+ - [External Documentation Object](#externalDocumentationObject)
+ - [Parameter Object](#parameterObject)
+ - [Request Body Object](#requestBodyObject)
+ - [Media Type Object](#mediaTypeObject)
+ - [Encoding Object](#encodingObject)
+ - [Responses Object](#responsesObject)
+ - [Response Object](#responseObject)
+ - [Callback Object](#callbackObject)
+ - [Example Object](#exampleObject)
+ - [Link Object](#linkObject)
+ - [Header Object](#headerObject)
+ - [Tag Object](#tagObject)
+ - [Reference Object](#referenceObject)
+ - [Schema Object](#schemaObject)
+ - [Discriminator Object](#discriminatorObject)
+ - [XML Object](#xmlObject)
+ - [Security Scheme Object](#securitySchemeObject)
+ - [OAuth Flows Object](#oauthFlowsObject)
+ - [OAuth Flow Object](#oauthFlowObject)
+ - [Security Requirement Object](#securityRequirementObject)
+ - [Specification Extensions](#specificationExtensions)
+ - [Security Filtering](#securityFiltering)
+- [Appendix A: Revision History](#revisionHistory)
+
+
+
+
+## Definitions
+
+##### OpenAPI Document
+A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
+
+##### Path Templating
+Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
+
+##### Media Types
+Media type definitions are spread across several resources.
+The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838).
+
+Some examples of possible media type definitions:
+```
+ text/plain; charset=utf-8
+ application/json
+ application/vnd.github+json
+ application/vnd.github.v3+json
+ application/vnd.github.v3.raw+json
+ application/vnd.github.v3.text+json
+ application/vnd.github.v3.html+json
+ application/vnd.github.v3.full+json
+ application/vnd.github.v3.diff
+ application/vnd.github.v3.patch
+```
+##### HTTP Status Codes
+The HTTP Status Codes are used to indicate the status of the executed operation.
+The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+
+## Specification
+
+### Versions
+
+The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+
+The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
+
+Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
+
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)
+
+### Format
+
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+
+For example, if a field has an array value, the JSON array representation will be used:
+
+```json
+{
+ "field": [ 1, 2, 3 ]
+}
+```
+All field names in the specification are **case sensitive**.
+This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
+
+The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+
+Patterned fields MUST have unique names within the containing object.
+
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
+
+- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346).
+
+**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
+
+### Document Structure
+
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions.
+
+It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
+
+### Data Types
+
+Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
+Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
+`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
+Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00.
+
+Primitives have an optional modifier property: `format`.
+OAS uses several known formats to define in fine detail the data type being used.
+However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
+Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
+
+The formats defined by the OAS are:
+
+[`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
+------ | -------- | --------
+`integer` | `int32` | signed 32 bits
+`integer` | `int64` | signed 64 bits (a.k.a long)
+`number` | `float` | |
+`number` | `double` | |
+`string` | | |
+`string` | `byte` | base64 encoded characters
+`string` | `binary` | any sequence of octets
+`boolean` | | |
+`string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+`string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+`string` | `password` | A hint to UIs to obscure input.
+
+
+### Rich Text Formatting
+Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
+
+### Relative References in URLs
+
+Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
+
+Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
+
+### Schema
+
+In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
+
+#### OpenAPI Object
+
+This is the root document object of the [OpenAPI document](#oasDocument).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
+info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
+paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
+components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
+tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Info Object
+
+The object provides metadata about the API.
+The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+title | `string` | **REQUIRED**. The title of the application.
+description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
+contact | [Contact Object](#contactObject) | The contact information for the exposed API.
+license | [License Object](#licenseObject) | The license information for the exposed API.
+version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Info Object Example
+
+```json
+{
+ "title": "Sample Pet Store App",
+ "description": "This is a sample server for a pet store.",
+ "termsOfService": "http://example.com/terms/",
+ "contact": {
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+ },
+ "version": "1.0.1"
+}
+```
+
+```yaml
+title: Sample Pet Store App
+description: This is a sample server for a pet store.
+termsOfService: http://example.com/terms/
+contact:
+ name: API Support
+ url: http://www.example.com/support
+ email: support@example.com
+license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+version: 1.0.1
+```
+
+#### Contact Object
+
+Contact information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | The identifying name of the contact person/organization.
+url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
+email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Contact Object Example
+
+```json
+{
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+}
+```
+
+```yaml
+name: API Support
+url: http://www.example.com/support
+email: support@example.com
+```
+
+#### License Object
+
+License information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The license name used for the API.
+url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### License Object Example
+
+```json
+{
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+}
+```
+
+```yaml
+name: Apache 2.0
+url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+#### Server Object
+
+An object representing a Server.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Server Object Example
+
+A single server would be described as:
+
+```json
+{
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+}
+```
+
+```yaml
+url: https://development.gigantic-server.com/v1
+description: Development server
+```
+
+The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+ },
+ {
+ "url": "https://staging.gigantic-server.com/v1",
+ "description": "Staging server"
+ },
+ {
+ "url": "https://api.gigantic-server.com/v1",
+ "description": "Production server"
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+ description: Development server
+- url: https://staging.gigantic-server.com/v1
+ description: Staging server
+- url: https://api.gigantic-server.com/v1
+ description: Production server
+```
+
+The following shows how variables can be used for a server configuration:
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
+ "description": "The production API server",
+ "variables": {
+ "username": {
+ "default": "demo",
+ "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+ },
+ "port": {
+ "enum": [
+ "8443",
+ "443"
+ ],
+ "default": "8443"
+ },
+ "basePath": {
+ "default": "v2"
+ }
+ }
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+ description: The production API server
+ variables:
+ username:
+ # note! no enum here means it is an open value
+ default: demo
+ description: this value is assigned by the service provider, in this example `gigantic-server.com`
+ port:
+ enum:
+ - '8443'
+ - '443'
+ default: '8443'
+ basePath:
+ # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+ default: v2
+```
+
+
+#### Server Variable Object
+
+An object representing a Server Variable for server URL template substitution.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set.
+default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional.
+description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Components Object
+
+Holds a set of reusable objects for different aspects of the OAS.
+All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+ schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+ responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
+ parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
+ examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
+ requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
+ headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
+ securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
+ links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
+ callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+
+Field Name Examples:
+
+```
+User
+User_1
+User_Name
+user-name
+my.org.User
+```
+
+##### Components Object Example
+
+```json
+"components": {
+ "schemas": {
+ "GeneralError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "integer",
+ "format": "int32"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
+ "Category": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "Tag": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "parameters": {
+ "skipParam": {
+ "name": "skip",
+ "in": "query",
+ "description": "number of items to skip",
+ "required": true,
+ "schema": {
+ "type": "integer",
+ "format": "int32"
+ }
+ },
+ "limitParam": {
+ "name": "limit",
+ "in": "query",
+ "description": "max records to return",
+ "required": true,
+ "schema" : {
+ "type": "integer",
+ "format": "int32"
+ }
+ }
+ },
+ "responses": {
+ "NotFound": {
+ "description": "Entity not found."
+ },
+ "IllegalInput": {
+ "description": "Illegal input for operation."
+ },
+ "GeneralError": {
+ "description": "General Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GeneralError"
+ }
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "http://example.org/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+components:
+ schemas:
+ GeneralError:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ message:
+ type: string
+ Category:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ Tag:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ parameters:
+ skipParam:
+ name: skip
+ in: query
+ description: number of items to skip
+ required: true
+ schema:
+ type: integer
+ format: int32
+ limitParam:
+ name: limit
+ in: query
+ description: max records to return
+ required: true
+ schema:
+ type: integer
+ format: int32
+ responses:
+ NotFound:
+ description: Entity not found.
+ IllegalInput:
+ description: Illegal input for operation.
+ GeneralError:
+ description: General Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GeneralError'
+ securitySchemes:
+ api_key:
+ type: apiKey
+ name: api_key
+ in: header
+ petstore_auth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: http://example.org/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+
+#### Paths Object
+
+Holds the relative paths to the individual endpoints and their operations.
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+ /pets/{petId}
+ /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+ /pets/{petId}
+ /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+ /{entity}/me
+ /books/{id}
+```
+
+##### Paths Object Example
+
+```json
+{
+ "/pets": {
+ "get": {
+ "description": "Returns all pets from the system that the user has access to",
+ "responses": {
+ "200": {
+ "description": "A list of pets.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/pet"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+/pets:
+ get:
+ description: Returns all pets from the system that the user has access to
+ responses:
+ '200':
+ description: A list of pets.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/pet'
+```
+
+#### Path Item Object
+
+Describes the operations available on a single path.
+A Path Item MAY be empty, due to [ACL constraints](#securityFiltering).
+The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*.
+summary| `string` | An optional, string summary, intended to apply to all operations in this path.
+description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
+put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
+post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
+delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
+options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
+head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
+patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
+trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Item Object Example
+
+```json
+{
+ "get": {
+ "description": "Returns pets based on ID",
+ "summary": "Find pets by ID",
+ "operationId": "getPetsById",
+ "responses": {
+ "200": {
+ "description": "pet response",
+ "content": {
+ "*/*": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Pet"
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "error payload",
+ "content": {
+ "text/html": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorModel"
+ }
+ }
+ }
+ }
+ }
+ },
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "description": "ID of pet to use",
+ "required": true,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "style": "simple"
+ }
+ ]
+}
+```
+
+```yaml
+get:
+ description: Returns pets based on ID
+ summary: Find pets by ID
+ operationId: getPetsById
+ responses:
+ '200':
+ description: pet response
+ content:
+ '*/*' :
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Pet'
+ default:
+ description: error payload
+ content:
+ 'text/html':
+ schema:
+ $ref: '#/components/schemas/ErrorModel'
+parameters:
+- name: id
+ in: path
+ description: ID of pet to use
+ required: true
+ schema:
+ type: array
+ style: simple
+ items:
+ type: string
+```
+
+#### Operation Object
+
+Describes a single API operation on a path.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
+summary | `string` | A short summary of what the operation does.
+description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
+operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
+responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation.
+callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
+deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Operation Object Example
+
+```json
+{
+ "tags": [
+ "pet"
+ ],
+ "summary": "Updates a pet in the store with form data",
+ "operationId": "updatePetWithForm",
+ "parameters": [
+ {
+ "name": "petId",
+ "in": "path",
+ "description": "ID of pet that needs to be updated",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "description": "Updated name of the pet",
+ "type": "string"
+ },
+ "status": {
+ "description": "Updated status of the pet",
+ "type": "string"
+ }
+ },
+ "required": ["status"]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Pet updated.",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ },
+ "405": {
+ "description": "Method Not Allowed",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ }
+ },
+ "security": [
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+tags:
+- pet
+summary: Updates a pet in the store with form data
+operationId: updatePetWithForm
+parameters:
+- name: petId
+ in: path
+ description: ID of pet that needs to be updated
+ required: true
+ schema:
+ type: string
+requestBody:
+ content:
+ 'application/x-www-form-urlencoded':
+ schema:
+ properties:
+ name:
+ description: Updated name of the pet
+ type: string
+ status:
+ description: Updated status of the pet
+ type: string
+ required:
+ - status
+responses:
+ '200':
+ description: Pet updated.
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+ '405':
+ description: Method Not Allowed
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+security:
+- petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+
+#### External Documentation Object
+
+Allows referencing an external resource for extended documentation.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### External Documentation Object Example
+
+```json
+{
+ "description": "Find more info here",
+ "url": "https://example.com"
+}
+```
+
+```yaml
+description: Find more info here
+url: https://example.com
+```
+
+#### Parameter Object
+
+Describes a single operation parameter.
+
+A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
+
+##### Parameter Locations
+There are four possible parameter locations specified by the `in` field:
+* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
+* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* cookie - Used to pass a specific cookie value to the API.
+
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. ...
+```
+
+Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default):
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+```
+
+```xml
+...
+...
+...
+```
+
+###### XML Name Replacement
+
+```json
+{
+ "animals": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+...
+```
+
+
+###### XML Attribute, Prefix and Namespace
+
+In this example, a full model definition is shown.
+
+```json
+{
+ "Person": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int32",
+ "xml": {
+ "attribute": true
+ }
+ },
+ "name": {
+ "type": "string",
+ "xml": {
+ "namespace": "http://example.com/schema/sample",
+ "prefix": "sample"
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+Person:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int32
+ xml:
+ attribute: true
+ name:
+ type: string
+ xml:
+ namespace: http://example.com/schema/sample
+ prefix: sample
+```
+
+```xml
+
+ example
+
+```
+
+###### XML Arrays
+
+Changing the element names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+value
+value
+```
+
+The external `name` property has no effect on the XML:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+```
+
+```xml
+value
+value
+```
+
+Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+To overcome the naming problem in the example above, the following definition can be used:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+Affecting both internal and external names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+If we change the external element but not the internal ones:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+#### Security Scheme Object
+
+Defines a security scheme that can be used by the operations.
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
+description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
+name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
+in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
+scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).
+bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
+openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Security Scheme Object Example
+
+###### Basic Authentication Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "basic"
+}
+```
+
+```yaml
+type: http
+scheme: basic
+```
+
+###### API Key Sample
+
+```json
+{
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+}
+```
+
+```yaml
+type: apiKey
+name: api_key
+in: header
+```
+
+###### JWT Bearer Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "JWT",
+}
+```
+
+```yaml
+type: http
+scheme: bearer
+bearerFormat: JWT
+```
+
+###### Implicit OAuth2 Sample
+
+```json
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow
+password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow
+clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
+authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL.
+tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL.
+refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### OAuth Flow Object Examples
+
+```JSON
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "tokenUrl": "https://example.com/api/oauth/token",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+ authorizationCode:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ tokenUrl: https://example.com/api/oauth/token
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+
+#### Security Requirement Object
+
+Lists the required security schemes to execute this operation.
+The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject).
+
+Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
+This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
+
+When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.
+
+##### Security Requirement Object Examples
+
+###### Non-OAuth2 Security Requirement
+
+```json
+{
+ "api_key": []
+}
+```
+
+```yaml
+api_key: []
+```
+
+###### OAuth2 Security Requirement
+
+```json
+{
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+}
+```
+
+```yaml
+petstore_auth:
+- write:pets
+- read:pets
+```
+
+### Specification Extensions
+
+While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
+
+The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+
+Field Pattern | Type | Description
+---|:---:|---
+^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value.
+
+The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
+
+### Security Filtering
+
+Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.
+
+The reasoning is to allow an additional layer of access control over the documentation.
+While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.
+
+Two examples of this:
+
+1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
+2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
+
+## Appendix A: Revision History
+
+Version | Date | Notes
+--- | --- | ---
+3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2
+3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
+3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
+3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
+3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification
+3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification
+2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative
+2.0 | 2014-09-08 | Release of Swagger 2.0
+1.2 | 2014-03-14 | Initial release of the formal document.
+1.1 | 2012-08-22 | Release of Swagger 1.1
+1.0 | 2011-08-10 | First release of the Swagger Specification
diff --git a/versions/3.0.3.md b/versions/3.0.3.md
new file mode 100644
index 0000000000..e21aa46554
--- /dev/null
+++ b/versions/3.0.3.md
@@ -0,0 +1,3454 @@
+# OpenAPI Specification
+
+#### Version 3.0.3
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+## Introduction
+
+The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
+
+## Table of Contents
+
+
+- [Definitions](#definitions)
+ - [OpenAPI Document](#oasDocument)
+ - [Path Templating](#pathTemplating)
+ - [Media Types](#mediaTypes)
+ - [HTTP Status Codes](#httpCodes)
+- [Specification](#specification)
+ - [Versions](#versions)
+ - [Format](#format)
+ - [Document Structure](#documentStructure)
+ - [Data Types](#dataTypes)
+ - [Rich Text Formatting](#richText)
+ - [Relative References In URLs](#relativeReferences)
+ - [Schema](#schema)
+ - [OpenAPI Object](#oasObject)
+ - [Info Object](#infoObject)
+ - [Contact Object](#contactObject)
+ - [License Object](#licenseObject)
+ - [Server Object](#serverObject)
+ - [Server Variable Object](#serverVariableObject)
+ - [Components Object](#componentsObject)
+ - [Paths Object](#pathsObject)
+ - [Path Item Object](#pathItemObject)
+ - [Operation Object](#operationObject)
+ - [External Documentation Object](#externalDocumentationObject)
+ - [Parameter Object](#parameterObject)
+ - [Request Body Object](#requestBodyObject)
+ - [Media Type Object](#mediaTypeObject)
+ - [Encoding Object](#encodingObject)
+ - [Responses Object](#responsesObject)
+ - [Response Object](#responseObject)
+ - [Callback Object](#callbackObject)
+ - [Example Object](#exampleObject)
+ - [Link Object](#linkObject)
+ - [Header Object](#headerObject)
+ - [Tag Object](#tagObject)
+ - [Reference Object](#referenceObject)
+ - [Schema Object](#schemaObject)
+ - [Discriminator Object](#discriminatorObject)
+ - [XML Object](#xmlObject)
+ - [Security Scheme Object](#securitySchemeObject)
+ - [OAuth Flows Object](#oauthFlowsObject)
+ - [OAuth Flow Object](#oauthFlowObject)
+ - [Security Requirement Object](#securityRequirementObject)
+ - [Specification Extensions](#specificationExtensions)
+ - [Security Filtering](#securityFiltering)
+- [Appendix A: Revision History](#revisionHistory)
+
+
+
+
+## Definitions
+
+##### OpenAPI Document
+A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
+
+##### Path Templating
+Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
+
+Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object).
+
+##### Media Types
+Media type definitions are spread across several resources.
+The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838).
+
+Some examples of possible media type definitions:
+```
+ text/plain; charset=utf-8
+ application/json
+ application/vnd.github+json
+ application/vnd.github.v3+json
+ application/vnd.github.v3.raw+json
+ application/vnd.github.v3.text+json
+ application/vnd.github.v3.html+json
+ application/vnd.github.v3.full+json
+ application/vnd.github.v3.diff
+ application/vnd.github.v3.patch
+```
+##### HTTP Status Codes
+The HTTP Status Codes are used to indicate the status of the executed operation.
+The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+
+## Specification
+
+### Versions
+
+The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+
+The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
+
+Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the `openapi` property to the new minor version.
+
+For example, a valid OpenAPI 3.0.2 document, upon changing its `openapi` property to `3.1.0`, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility.
+
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)
+
+### Format
+
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+
+For example, if a field has an array value, the JSON array representation will be used:
+
+```json
+{
+ "field": [ 1, 2, 3 ]
+}
+```
+All field names in the specification are **case sensitive**.
+This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
+
+The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+
+Patterned fields MUST have unique names within the containing object.
+
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
+
+- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).
+
+**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
+
+### Document Structure
+
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions.
+
+It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
+
+### Data Types
+
+Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
+Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
+`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
+Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00.
+
+Primitives have an optional modifier property: `format`.
+OAS uses several known formats to define in fine detail the data type being used.
+However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
+Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
+
+The formats defined by the OAS are:
+
+[`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
+------ | -------- | --------
+`integer` | `int32` | signed 32 bits
+`integer` | `int64` | signed 64 bits (a.k.a long)
+`number` | `float` | |
+`number` | `double` | |
+`string` | | |
+`string` | `byte` | base64 encoded characters
+`string` | `binary` | any sequence of octets
+`boolean` | | |
+`string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+`string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
+`string` | `password` | A hint to UIs to obscure input.
+
+
+### Rich Text Formatting
+Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
+
+### Relative References in URLs
+
+Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
+
+Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
+
+### Schema
+
+In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
+
+#### OpenAPI Object
+
+This is the root document object of the [OpenAPI document](#oasDocument).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
+info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
+paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
+components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array.
+tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Info Object
+
+The object provides metadata about the API.
+The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+title | `string` | **REQUIRED**. The title of the API.
+description | `string` | A short description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
+contact | [Contact Object](#contactObject) | The contact information for the exposed API.
+license | [License Object](#licenseObject) | The license information for the exposed API.
+version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Info Object Example
+
+```json
+{
+ "title": "Sample Pet Store App",
+ "description": "This is a sample server for a pet store.",
+ "termsOfService": "http://example.com/terms/",
+ "contact": {
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+ },
+ "version": "1.0.1"
+}
+```
+
+```yaml
+title: Sample Pet Store App
+description: This is a sample server for a pet store.
+termsOfService: http://example.com/terms/
+contact:
+ name: API Support
+ url: http://www.example.com/support
+ email: support@example.com
+license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+version: 1.0.1
+```
+
+#### Contact Object
+
+Contact information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | The identifying name of the contact person/organization.
+url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
+email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Contact Object Example
+
+```json
+{
+ "name": "API Support",
+ "url": "http://www.example.com/support",
+ "email": "support@example.com"
+}
+```
+
+```yaml
+name: API Support
+url: http://www.example.com/support
+email: support@example.com
+```
+
+#### License Object
+
+License information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The license name used for the API.
+url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### License Object Example
+
+```json
+{
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+}
+```
+
+```yaml
+name: Apache 2.0
+url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+#### Server Object
+
+An object representing a Server.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Server Object Example
+
+A single server would be described as:
+
+```json
+{
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+}
+```
+
+```yaml
+url: https://development.gigantic-server.com/v1
+description: Development server
+```
+
+The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+ },
+ {
+ "url": "https://staging.gigantic-server.com/v1",
+ "description": "Staging server"
+ },
+ {
+ "url": "https://api.gigantic-server.com/v1",
+ "description": "Production server"
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+ description: Development server
+- url: https://staging.gigantic-server.com/v1
+ description: Staging server
+- url: https://api.gigantic-server.com/v1
+ description: Production server
+```
+
+The following shows how variables can be used for a server configuration:
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
+ "description": "The production API server",
+ "variables": {
+ "username": {
+ "default": "demo",
+ "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+ },
+ "port": {
+ "enum": [
+ "8443",
+ "443"
+ ],
+ "default": "8443"
+ },
+ "basePath": {
+ "default": "v2"
+ }
+ }
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+ description: The production API server
+ variables:
+ username:
+ # note! no enum here means it is an open value
+ default: demo
+ description: this value is assigned by the service provider, in this example `gigantic-server.com`
+ port:
+ enum:
+ - '8443'
+ - '443'
+ default: '8443'
+ basePath:
+ # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+ default: v2
+```
+
+
+#### Server Variable Object
+
+An object representing a Server Variable for server URL template substitution.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty.
+default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values.
+description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Components Object
+
+Holds a set of reusable objects for different aspects of the OAS.
+All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+ schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+ responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
+ parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
+ examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
+ requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
+ headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
+ securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
+ links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
+ callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+
+Field Name Examples:
+
+```
+User
+User_1
+User_Name
+user-name
+my.org.User
+```
+
+##### Components Object Example
+
+```json
+"components": {
+ "schemas": {
+ "GeneralError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "integer",
+ "format": "int32"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
+ "Category": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "Tag": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "parameters": {
+ "skipParam": {
+ "name": "skip",
+ "in": "query",
+ "description": "number of items to skip",
+ "required": true,
+ "schema": {
+ "type": "integer",
+ "format": "int32"
+ }
+ },
+ "limitParam": {
+ "name": "limit",
+ "in": "query",
+ "description": "max records to return",
+ "required": true,
+ "schema" : {
+ "type": "integer",
+ "format": "int32"
+ }
+ }
+ },
+ "responses": {
+ "NotFound": {
+ "description": "Entity not found."
+ },
+ "IllegalInput": {
+ "description": "Illegal input for operation."
+ },
+ "GeneralError": {
+ "description": "General Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GeneralError"
+ }
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "http://example.org/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+components:
+ schemas:
+ GeneralError:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ message:
+ type: string
+ Category:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ Tag:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ parameters:
+ skipParam:
+ name: skip
+ in: query
+ description: number of items to skip
+ required: true
+ schema:
+ type: integer
+ format: int32
+ limitParam:
+ name: limit
+ in: query
+ description: max records to return
+ required: true
+ schema:
+ type: integer
+ format: int32
+ responses:
+ NotFound:
+ description: Entity not found.
+ IllegalInput:
+ description: Illegal input for operation.
+ GeneralError:
+ description: General Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GeneralError'
+ securitySchemes:
+ api_key:
+ type: apiKey
+ name: api_key
+ in: header
+ petstore_auth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: http://example.org/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+
+#### Paths Object
+
+Holds the relative paths to the individual endpoints and their operations.
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+ /pets/{petId}
+ /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+ /pets/{petId}
+ /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+ /{entity}/me
+ /books/{id}
+```
+
+##### Paths Object Example
+
+```json
+{
+ "/pets": {
+ "get": {
+ "description": "Returns all pets from the system that the user has access to",
+ "responses": {
+ "200": {
+ "description": "A list of pets.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/pet"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+/pets:
+ get:
+ description: Returns all pets from the system that the user has access to
+ responses:
+ '200':
+ description: A list of pets.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/pet'
+```
+
+#### Path Item Object
+
+Describes the operations available on a single path.
+A Path Item MAY be empty, due to [ACL constraints](#securityFiltering).
+The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined.
+summary| `string` | An optional, string summary, intended to apply to all operations in this path.
+description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
+put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
+post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
+delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
+options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
+head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
+patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
+trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Item Object Example
+
+```json
+{
+ "get": {
+ "description": "Returns pets based on ID",
+ "summary": "Find pets by ID",
+ "operationId": "getPetsById",
+ "responses": {
+ "200": {
+ "description": "pet response",
+ "content": {
+ "*/*": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Pet"
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "error payload",
+ "content": {
+ "text/html": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorModel"
+ }
+ }
+ }
+ }
+ }
+ },
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "description": "ID of pet to use",
+ "required": true,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "style": "simple"
+ }
+ ]
+}
+```
+
+```yaml
+get:
+ description: Returns pets based on ID
+ summary: Find pets by ID
+ operationId: getPetsById
+ responses:
+ '200':
+ description: pet response
+ content:
+ '*/*' :
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Pet'
+ default:
+ description: error payload
+ content:
+ 'text/html':
+ schema:
+ $ref: '#/components/schemas/ErrorModel'
+parameters:
+- name: id
+ in: path
+ description: ID of pet to use
+ required: true
+ schema:
+ type: array
+ items:
+ type: string
+ style: simple
+```
+
+#### Operation Object
+
+Describes a single API operation on a path.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
+summary | `string` | A short summary of what the operation does.
+description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
+operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
+responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation.
+callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.
+deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Operation Object Example
+
+```json
+{
+ "tags": [
+ "pet"
+ ],
+ "summary": "Updates a pet in the store with form data",
+ "operationId": "updatePetWithForm",
+ "parameters": [
+ {
+ "name": "petId",
+ "in": "path",
+ "description": "ID of pet that needs to be updated",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "description": "Updated name of the pet",
+ "type": "string"
+ },
+ "status": {
+ "description": "Updated status of the pet",
+ "type": "string"
+ }
+ },
+ "required": ["status"]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Pet updated.",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ },
+ "405": {
+ "description": "Method Not Allowed",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ }
+ },
+ "security": [
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+tags:
+- pet
+summary: Updates a pet in the store with form data
+operationId: updatePetWithForm
+parameters:
+- name: petId
+ in: path
+ description: ID of pet that needs to be updated
+ required: true
+ schema:
+ type: string
+requestBody:
+ content:
+ 'application/x-www-form-urlencoded':
+ schema:
+ properties:
+ name:
+ description: Updated name of the pet
+ type: string
+ status:
+ description: Updated status of the pet
+ type: string
+ required:
+ - status
+responses:
+ '200':
+ description: Pet updated.
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+ '405':
+ description: Method Not Allowed
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+security:
+- petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+
+#### External Documentation Object
+
+Allows referencing an external resource for extended documentation.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### External Documentation Object Example
+
+```json
+{
+ "description": "Find more info here",
+ "url": "https://example.com"
+}
+```
+
+```yaml
+description: Find more info here
+url: https://example.com
+```
+
+#### Parameter Object
+
+Describes a single operation parameter.
+
+A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
+
+##### Parameter Locations
+There are four possible parameter locations specified by the `in` field:
+* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
+* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* cookie - Used to pass a specific cookie value to the API.
+
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. ...
+```
+
+Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default):
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+```
+
+```xml
+...
+...
+...
+```
+
+###### XML Name Replacement
+
+```json
+{
+ "animals": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+...
+```
+
+
+###### XML Attribute, Prefix and Namespace
+
+In this example, a full model definition is shown.
+
+```json
+{
+ "Person": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int32",
+ "xml": {
+ "attribute": true
+ }
+ },
+ "name": {
+ "type": "string",
+ "xml": {
+ "namespace": "http://example.com/schema/sample",
+ "prefix": "sample"
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+Person:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int32
+ xml:
+ attribute: true
+ name:
+ type: string
+ xml:
+ namespace: http://example.com/schema/sample
+ prefix: sample
+```
+
+```xml
+
+ example
+
+```
+
+###### XML Arrays
+
+Changing the element names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+value
+value
+```
+
+The external `name` property has no effect on the XML:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+```
+
+```xml
+value
+value
+```
+
+Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+To overcome the naming problem in the example above, the following definition can be used:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+Affecting both internal and external names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+If we change the external element but not the internal ones:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+#### Security Scheme Object
+
+Defines a security scheme that can be used by the operations.
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
+description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
+in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
+scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).
+bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
+openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Security Scheme Object Example
+
+###### Basic Authentication Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "basic"
+}
+```
+
+```yaml
+type: http
+scheme: basic
+```
+
+###### API Key Sample
+
+```json
+{
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+}
+```
+
+```yaml
+type: apiKey
+name: api_key
+in: header
+```
+
+###### JWT Bearer Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "JWT",
+}
+```
+
+```yaml
+type: http
+scheme: bearer
+bearerFormat: JWT
+```
+
+###### Implicit OAuth2 Sample
+
+```json
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow
+password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow
+clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
+authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL.
+tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL.
+refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### OAuth Flow Object Examples
+
+```JSON
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "tokenUrl": "https://example.com/api/oauth/token",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+ authorizationCode:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ tokenUrl: https://example.com/api/oauth/token
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### Security Requirement Object
+
+Lists the required security schemes to execute this operation.
+The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject).
+
+Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
+This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
+
+When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty.
+
+##### Security Requirement Object Examples
+
+###### Non-OAuth2 Security Requirement
+
+```json
+{
+ "api_key": []
+}
+```
+
+```yaml
+api_key: []
+```
+
+###### OAuth2 Security Requirement
+
+```json
+{
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+}
+```
+
+```yaml
+petstore_auth:
+- write:pets
+- read:pets
+```
+
+###### Optional OAuth2 Security
+
+Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object:
+
+```json
+{
+ "security": [
+ {},
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+security:
+ - {}
+ - petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+### Specification Extensions
+
+While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
+
+The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+
+Field Pattern | Type | Description
+---|:---:|---
+^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value.
+
+The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
+
+### Security Filtering
+
+Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.
+
+The reasoning is to allow an additional layer of access control over the documentation.
+While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.
+
+Two examples of this:
+
+1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
+2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
+
+## Appendix A: Revision History
+
+Version | Date | Notes
+--- | --- | ---
+3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3
+3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2
+3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
+3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
+3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
+3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification
+3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification
+2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative
+2.0 | 2014-09-08 | Release of Swagger 2.0
+1.2 | 2014-03-14 | Initial release of the formal document.
+1.1 | 2012-08-22 | Release of Swagger 1.1
+1.0 | 2011-08-10 | First release of the Swagger Specification
diff --git a/versions/3.1.0.md b/versions/3.1.0.md
new file mode 100644
index 0000000000..39425bd6b9
--- /dev/null
+++ b/versions/3.1.0.md
@@ -0,0 +1,3468 @@
+# OpenAPI Specification
+
+#### Version 3.1.0
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
+
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+## Introduction
+
+The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
+
+## Table of Contents
+
+
+- [Definitions](#definitions)
+ - [OpenAPI Document](#oasDocument)
+ - [Path Templating](#pathTemplating)
+ - [Media Types](#mediaTypes)
+ - [HTTP Status Codes](#httpCodes)
+- [Specification](#specification)
+ - [Versions](#versions)
+ - [Format](#format)
+ - [Document Structure](#documentStructure)
+ - [Data Types](#dataTypes)
+ - [Rich Text Formatting](#richText)
+ - [Relative References In URIs](#relativeReferencesURI)
+ - [Relative References In URLs](#relativeReferencesURL)
+ - [Schema](#schema)
+ - [OpenAPI Object](#oasObject)
+ - [Info Object](#infoObject)
+ - [Contact Object](#contactObject)
+ - [License Object](#licenseObject)
+ - [Server Object](#serverObject)
+ - [Server Variable Object](#serverVariableObject)
+ - [Components Object](#componentsObject)
+ - [Paths Object](#pathsObject)
+ - [Path Item Object](#pathItemObject)
+ - [Operation Object](#operationObject)
+ - [External Documentation Object](#externalDocumentationObject)
+ - [Parameter Object](#parameterObject)
+ - [Request Body Object](#requestBodyObject)
+ - [Media Type Object](#mediaTypeObject)
+ - [Encoding Object](#encodingObject)
+ - [Responses Object](#responsesObject)
+ - [Response Object](#responseObject)
+ - [Callback Object](#callbackObject)
+ - [Example Object](#exampleObject)
+ - [Link Object](#linkObject)
+ - [Header Object](#headerObject)
+ - [Tag Object](#tagObject)
+ - [Reference Object](#referenceObject)
+ - [Schema Object](#schemaObject)
+ - [Discriminator Object](#discriminatorObject)
+ - [XML Object](#xmlObject)
+ - [Security Scheme Object](#securitySchemeObject)
+ - [OAuth Flows Object](#oauthFlowsObject)
+ - [OAuth Flow Object](#oauthFlowObject)
+ - [Security Requirement Object](#securityRequirementObject)
+ - [Specification Extensions](#specificationExtensions)
+ - [Security Filtering](#securityFiltering)
+- [Appendix A: Revision History](#revisionHistory)
+
+
+
+
+## Definitions
+
+##### OpenAPI Document
+A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification.
+
+##### Path Templating
+Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
+
+Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
+
+The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by [RFC3986](https://tools.ietf.org/html/rfc3986#section-3): forward slashes (`/`), question marks (`?`), or hashes (`#`).
+
+##### Media Types
+Media type definitions are spread across several resources.
+The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838).
+
+Some examples of possible media type definitions:
+```
+ text/plain; charset=utf-8
+ application/json
+ application/vnd.github+json
+ application/vnd.github.v3+json
+ application/vnd.github.v3.raw+json
+ application/vnd.github.v3.text+json
+ application/vnd.github.v3.html+json
+ application/vnd.github.v3.full+json
+ application/vnd.github.v3.diff
+ application/vnd.github.v3.patch
+```
+##### HTTP Status Codes
+The HTTP Status Codes are used to indicate the status of the executed operation.
+The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+
+## Specification
+
+### Versions
+
+The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example `3.1`) SHALL designate the OAS feature set. *`.patch`* versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.1.0` and `3.1.1` for example.
+
+Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided.
+
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the version of the OAS that it uses.
+
+### Format
+
+An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
+
+For example, if a field has an array value, the JSON array representation will be used:
+
+```json
+{
+ "field": [ 1, 2, 3 ]
+}
+```
+All field names in the specification are **case sensitive**.
+This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
+
+The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+
+Patterned fields MUST have unique names within the containing object.
+
+In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints:
+
+- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).
+- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346).
+
+**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
+
+### Document Structure
+
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used.
+
+It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
+
+### Data Types
+
+Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).
+Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
+Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12.
+
+As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`.
+OAS defines additional formats to provide fine detail for primitive data types.
+
+The formats defined by the OAS are:
+
+[`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
+------ | -------- | --------
+`integer` | `int32` | signed 32 bits
+`integer` | `int64` | signed 64 bits (a.k.a long)
+`number` | `float` | |
+`number` | `double` | |
+`string` | `password` | A hint to UIs to obscure input.
+
+### Rich Text Formatting
+Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
+Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns.
+
+### Relative References in URIs
+
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+
+Relative references, including those in [`Reference Objects`](#referenceObject), [`PathItem Object`](#pathItemObject) `$ref` fields, [`Link Object`](#linkObject) `operationRef` fields and [`Example Object`](#exampleObject) `externalValue` fields, are resolved using the referring document as the Base URI according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.2).
+
+If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901).
+
+Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2). If no parent schema contains an `$id`, then the Base URI MUST be determined according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1).
+
+### Relative References in URLs
+
+Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URL. Note that these themselves MAY be relative to the referring document.
+
+### Schema
+
+In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.
+
+#### OpenAPI Object
+
+This is the root object of the [OpenAPI document](#oasDocument).
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
+info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
+ jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schemaObject) contained within this OAS document. This MUST be in the form of a URI.
+servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
+paths | [Paths Object](#pathsObject) | The available paths and operations for the API.
+webhooks | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available.
+components | [Components Object](#componentsObject) | An element to hold various schemas for the document.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array.
+tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Info Object
+
+The object provides metadata about the API.
+The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+title | `string` | **REQUIRED**. The title of the API.
+summary | `string` | A short summary of the API.
+description | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of a URL.
+contact | [Contact Object](#contactObject) | The contact information for the exposed API.
+license | [License Object](#licenseObject) | The license information for the exposed API.
+version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Info Object Example
+
+```json
+{
+ "title": "Sample Pet Store App",
+ "summary": "A pet store manager.",
+ "description": "This is a sample server for a pet store.",
+ "termsOfService": "https://example.com/terms/",
+ "contact": {
+ "name": "API Support",
+ "url": "https://www.example.com/support",
+ "email": "support@example.com"
+ },
+ "license": {
+ "name": "Apache 2.0",
+ "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+ },
+ "version": "1.0.1"
+}
+```
+
+```yaml
+title: Sample Pet Store App
+summary: A pet store manager.
+description: This is a sample server for a pet store.
+termsOfService: https://example.com/terms/
+contact:
+ name: API Support
+ url: https://www.example.com/support
+ email: support@example.com
+license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+version: 1.0.1
+```
+
+#### Contact Object
+
+Contact information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | The identifying name of the contact person/organization.
+url | `string` | The URL pointing to the contact information. This MUST be in the form of a URL.
+email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Contact Object Example
+
+```json
+{
+ "name": "API Support",
+ "url": "https://www.example.com/support",
+ "email": "support@example.com"
+}
+```
+
+```yaml
+name: API Support
+url: https://www.example.com/support
+email: support@example.com
+```
+
+#### License Object
+
+License information for the exposed API.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The license name used for the API.
+identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.
+url | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### License Object Example
+
+```json
+{
+ "name": "Apache 2.0",
+ "identifier": "Apache-2.0"
+}
+```
+
+```yaml
+name: Apache 2.0
+identifier: Apache-2.0
+```
+
+#### Server Object
+
+An object representing a Server.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Server Object Example
+
+A single server would be described as:
+
+```json
+{
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+}
+```
+
+```yaml
+url: https://development.gigantic-server.com/v1
+description: Development server
+```
+
+The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://development.gigantic-server.com/v1",
+ "description": "Development server"
+ },
+ {
+ "url": "https://staging.gigantic-server.com/v1",
+ "description": "Staging server"
+ },
+ {
+ "url": "https://api.gigantic-server.com/v1",
+ "description": "Production server"
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+ description: Development server
+- url: https://staging.gigantic-server.com/v1
+ description: Staging server
+- url: https://api.gigantic-server.com/v1
+ description: Production server
+```
+
+The following shows how variables can be used for a server configuration:
+
+```json
+{
+ "servers": [
+ {
+ "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
+ "description": "The production API server",
+ "variables": {
+ "username": {
+ "default": "demo",
+ "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+ },
+ "port": {
+ "enum": [
+ "8443",
+ "443"
+ ],
+ "default": "8443"
+ },
+ "basePath": {
+ "default": "v2"
+ }
+ }
+ }
+ ]
+}
+```
+
+```yaml
+servers:
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+ description: The production API server
+ variables:
+ username:
+ # note! no enum here means it is an open value
+ default: demo
+ description: this value is assigned by the service provider, in this example `gigantic-server.com`
+ port:
+ enum:
+ - '8443'
+ - '443'
+ default: '8443'
+ basePath:
+ # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+ default: v2
+```
+
+
+#### Server Variable Object
+
+An object representing a Server Variable for server URL template substitution.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty.
+default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value MUST exist in the enum's values.
+description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### Components Object
+
+Holds a set of reusable objects for different aspects of the OAS.
+All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.
+
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---|---
+ schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
+ responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
+ parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
+ examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
+ requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
+ headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
+ securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
+ links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
+ callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
+ pathItems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
+
+Field Name Examples:
+
+```
+User
+User_1
+User_Name
+user-name
+my.org.User
+```
+
+##### Components Object Example
+
+```json
+"components": {
+ "schemas": {
+ "GeneralError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "integer",
+ "format": "int32"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
+ "Category": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
+ "Tag": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "parameters": {
+ "skipParam": {
+ "name": "skip",
+ "in": "query",
+ "description": "number of items to skip",
+ "required": true,
+ "schema": {
+ "type": "integer",
+ "format": "int32"
+ }
+ },
+ "limitParam": {
+ "name": "limit",
+ "in": "query",
+ "description": "max records to return",
+ "required": true,
+ "schema" : {
+ "type": "integer",
+ "format": "int32"
+ }
+ }
+ },
+ "responses": {
+ "NotFound": {
+ "description": "Entity not found."
+ },
+ "IllegalInput": {
+ "description": "Illegal input for operation."
+ },
+ "GeneralError": {
+ "description": "General Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GeneralError"
+ }
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "api_key": {
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+ },
+ "petstore_auth": {
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.org/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+components:
+ schemas:
+ GeneralError:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ message:
+ type: string
+ Category:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ Tag:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int64
+ name:
+ type: string
+ parameters:
+ skipParam:
+ name: skip
+ in: query
+ description: number of items to skip
+ required: true
+ schema:
+ type: integer
+ format: int32
+ limitParam:
+ name: limit
+ in: query
+ description: max records to return
+ required: true
+ schema:
+ type: integer
+ format: int32
+ responses:
+ NotFound:
+ description: Entity not found.
+ IllegalInput:
+ description: Illegal input for operation.
+ GeneralError:
+ description: General Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GeneralError'
+ securitySchemes:
+ api_key:
+ type: apiKey
+ name: api_key
+ in: header
+ petstore_auth:
+ type: oauth2
+ flows:
+ implicit:
+ authorizationUrl: https://example.org/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### Paths Object
+
+Holds the relative paths to the individual endpoints and their operations.
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering).
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Templating Matching
+
+Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used:
+
+```
+ /pets/{petId}
+ /pets/mine
+```
+
+The following paths are considered identical and invalid:
+
+```
+ /pets/{petId}
+ /pets/{name}
+```
+
+The following may lead to ambiguous resolution:
+
+```
+ /{entity}/me
+ /books/{id}
+```
+
+##### Paths Object Example
+
+```json
+{
+ "/pets": {
+ "get": {
+ "description": "Returns all pets from the system that the user has access to",
+ "responses": {
+ "200": {
+ "description": "A list of pets.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/pet"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+/pets:
+ get:
+ description: Returns all pets from the system that the user has access to
+ responses:
+ '200':
+ description: A list of pets.
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/pet'
+```
+
+#### Path Item Object
+
+Describes the operations available on a single path.
+A Path Item MAY be empty, due to [ACL constraints](#securityFiltering).
+The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relativeReferencesURI).
+summary| `string` | An optional, string summary, intended to apply to all operations in this path.
+description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
+put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
+post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
+delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path.
+options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path.
+head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
+patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
+trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Path Item Object Example
+
+```json
+{
+ "get": {
+ "description": "Returns pets based on ID",
+ "summary": "Find pets by ID",
+ "operationId": "getPetsById",
+ "responses": {
+ "200": {
+ "description": "pet response",
+ "content": {
+ "*/*": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Pet"
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "error payload",
+ "content": {
+ "text/html": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorModel"
+ }
+ }
+ }
+ }
+ }
+ },
+ "parameters": [
+ {
+ "name": "id",
+ "in": "path",
+ "description": "ID of pet to use",
+ "required": true,
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "style": "simple"
+ }
+ ]
+}
+```
+
+```yaml
+get:
+ description: Returns pets based on ID
+ summary: Find pets by ID
+ operationId: getPetsById
+ responses:
+ '200':
+ description: pet response
+ content:
+ '*/*' :
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Pet'
+ default:
+ description: error payload
+ content:
+ 'text/html':
+ schema:
+ $ref: '#/components/schemas/ErrorModel'
+parameters:
+- name: id
+ in: path
+ description: ID of pet to use
+ required: true
+ schema:
+ type: array
+ items:
+ type: string
+ style: simple
+```
+
+#### Operation Object
+
+Describes a single API operation on a path.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
+summary | `string` | A short summary of what the operation does.
+description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
+operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
+requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+responses | [Responses Object](#responsesObject) | The list of possible responses as they are returned from executing this operation.
+callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses.
+deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
+security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
+servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Operation Object Example
+
+```json
+{
+ "tags": [
+ "pet"
+ ],
+ "summary": "Updates a pet in the store with form data",
+ "operationId": "updatePetWithForm",
+ "parameters": [
+ {
+ "name": "petId",
+ "in": "path",
+ "description": "ID of pet that needs to be updated",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "description": "Updated name of the pet",
+ "type": "string"
+ },
+ "status": {
+ "description": "Updated status of the pet",
+ "type": "string"
+ }
+ },
+ "required": ["status"]
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Pet updated.",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ },
+ "405": {
+ "description": "Method Not Allowed",
+ "content": {
+ "application/json": {},
+ "application/xml": {}
+ }
+ }
+ },
+ "security": [
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+tags:
+- pet
+summary: Updates a pet in the store with form data
+operationId: updatePetWithForm
+parameters:
+- name: petId
+ in: path
+ description: ID of pet that needs to be updated
+ required: true
+ schema:
+ type: string
+requestBody:
+ content:
+ 'application/x-www-form-urlencoded':
+ schema:
+ type: object
+ properties:
+ name:
+ description: Updated name of the pet
+ type: string
+ status:
+ description: Updated status of the pet
+ type: string
+ required:
+ - status
+responses:
+ '200':
+ description: Pet updated.
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+ '405':
+ description: Method Not Allowed
+ content:
+ 'application/json': {}
+ 'application/xml': {}
+security:
+- petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+
+#### External Documentation Object
+
+Allows referencing an external resource for extended documentation.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+description | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+url | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### External Documentation Object Example
+
+```json
+{
+ "description": "Find more info here",
+ "url": "https://example.com"
+}
+```
+
+```yaml
+description: Find more info here
+url: https://example.com
+```
+
+#### Parameter Object
+
+Describes a single operation parameter.
+
+A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
+
+##### Parameter Locations
+There are four possible parameter locations specified by the `in` field:
+* path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
+* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* cookie - Used to pass a specific cookie value to the API.
+
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. + +This object MAY be extended with [Specification Extensions](#specificationExtensions), though as noted, additional properties MAY omit the `x-` prefix within this object. + +###### Composition and Inheritance (Polymorphism) + +The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. +`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. + +While composition offers model extensibility, it does not imply a hierarchy between the models. +To support polymorphism, the OpenAPI Specification adds the `discriminator` field. +When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. +As such, the `discriminator` field MUST be a required field. +There are two ways to define the value of a discriminator for an inheriting instance. +- Use the schema name. +- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +###### XML Modeling + +The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. +The [XML Object](#xmlObject) contains additional information about the available options. + +###### Specifying Schema Dialects + +It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema. + +The `$schema` keyword MAY be present in any root Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. This allows use of Schema Objects which comply with other drafts of JSON Schema than the default Draft 2020-12 support. Tooling MUST support the OAS dialect schema id, and MAY support additional values of `$schema`. + +To allow use of a different default `$schema` value for all Schema Objects contained within an OAS document, a `jsonSchemaDialect` value may be set within the OpenAPI Object. If this default is not set, then the OAS dialect schema id MUST be used for these Schema Objects. The value of `$schema` within a Schema Object always overrides any default. + +When a Schema Object is referenced from an external resource which is not an OAS document (e.g. a bare JSON Schema resource), then the value of the `$schema` keyword for schemas within that resource MUST follow [JSON Schema rules](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.1.1). + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +type: object +required: +- name +properties: + name: + type: string + address: + $ref: '#/components/schemas/Address' + age: + type: integer + format: int32 + minimum: 0 +``` + +###### Model with Map/Dictionary Properties + +For a simple string to string mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "example": { + "name": "Puma", + "id": 1 + } +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +example: + name: Puma + id: 1 +``` + +###### Models with Composition + +```json +{ + "components": { + "schemas": { + "ErrorModel": { + "type": "object", + "required": [ + "message", + "code" + ], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "integer", + "minimum": 100, + "maximum": 600 + } + } + }, + "ExtendedErrorModel": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorModel" + }, + { + "type": "object", + "required": [ + "rootCause" + ], + "properties": { + "rootCause": { + "type": "string" + } + } + } + ] + } + } + } +} +``` + +```yaml +components: + schemas: + ErrorModel: + type: object + required: + - message + - code + properties: + message: + type: string + code: + type: integer + minimum: 100 + maximum: 600 + ExtendedErrorModel: + allOf: + - $ref: '#/components/schemas/ErrorModel' + - type: object + required: + - rootCause + properties: + rootCause: + type: string +``` + +###### Models with Polymorphism Support + +```json +{ + "components": { + "schemas": { + "Pet": { + "type": "object", + "discriminator": { + "propertyName": "petType" + }, + "properties": { + "name": { + "type": "string" + }, + "petType": { + "type": "string" + } + }, + "required": [ + "name", + "petType" + ] + }, + "Cat": { + "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "huntingSkill": { + "type": "string", + "description": "The measured skill for hunting", + "default": "lazy", + "enum": [ + "clueless", + "lazy", + "adventurous", + "aggressive" + ] + } + }, + "required": [ + "huntingSkill" + ] + } + ] + }, + "Dog": { + "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "packSize": { + "type": "integer", + "format": "int32", + "description": "the size of the pack the dog is from", + "default": 0, + "minimum": 0 + } + }, + "required": [ + "packSize" + ] + } + ] + } + } + } +} +``` + +```yaml +components: + schemas: + Pet: + type: object + discriminator: + propertyName: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + Cat: ## "Cat" will be used as the discriminator value + description: A representation of a cat + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + huntingSkill: + type: string + description: The measured skill for hunting + enum: + - clueless + - lazy + - adventurous + - aggressive + required: + - huntingSkill + Dog: ## "Dog" will be used as the discriminator value + description: A representation of a dog + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + packSize: + type: integer + format: int32 + description: the size of the pack the dog is from + default: 0 + minimum: 0 + required: + - packSize +``` + +#### Discriminator Object + +When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. + +When using the discriminator, _inline_ schemas will not be considered. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. + mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. + +In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' +``` + +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: + + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' + discriminator: + propertyName: petType +``` + +The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: + +```json +{ + "id": 12345, + "petType": "Cat" +} +``` + +Will indicate that the `Cat` schema be used in conjunction with this payload. + +In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' + - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' + discriminator: + propertyName: petType + mapping: + dog: '#/components/schemas/Dog' + monster: 'https://gigantic-server.com/schemas/Monster/schema.json' +``` + +Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. + +When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. + +In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. + +For example: + +```yaml +components: + schemas: + Pet: + type: object + required: + - petType + properties: + petType: + type: string + discriminator: + propertyName: petType + mapping: + dog: Dog + Cat: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Cat` + properties: + name: + type: string + Dog: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Dog` + properties: + bark: + type: string + Lizard: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Lizard` + properties: + lovesRocks: + type: boolean +``` + +a payload like this: + +```json +{ + "petType": "Cat", + "name": "misty" +} +``` + +will indicate that the `Cat` schema be used. Likewise this schema: + +```json +{ + "petType": "dog", + "bark": "soft" +} +``` + +will map to `Dog` because of the definition in the `mapping` element. + + +#### XML Object + +A metadata object that allows for more fine-tuned XML model definitions. + +When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. +See examples for expected behavior. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. +namespace | `string` | The URI of the namespace definition. This MUST be in the form of an absolute URI. +prefix | `string` | The prefix to be used for the [name](#xmlName). +attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. +wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `...
+```
+
+Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default):
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+```
+
+```xml
+...
+...
+...
+```
+
+###### XML Name Replacement
+
+```json
+{
+ "animals": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+...
+```
+
+
+###### XML Attribute, Prefix and Namespace
+
+In this example, a full model definition is shown.
+
+```json
+{
+ "Person": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "format": "int32",
+ "xml": {
+ "attribute": true
+ }
+ },
+ "name": {
+ "type": "string",
+ "xml": {
+ "namespace": "https://example.com/schema/sample",
+ "prefix": "sample"
+ }
+ }
+ }
+ }
+}
+```
+
+```yaml
+Person:
+ type: object
+ properties:
+ id:
+ type: integer
+ format: int32
+ xml:
+ attribute: true
+ name:
+ type: string
+ xml:
+ namespace: https://example.com/schema/sample
+ prefix: sample
+```
+
+```xml
+
+ example
+
+```
+
+###### XML Arrays
+
+Changing the element names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+```
+
+```xml
+value
+value
+```
+
+The external `name` property has no effect on the XML:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens"
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+```
+
+```xml
+value
+value
+```
+
+Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+To overcome the naming problem in the example above, the following definition can be used:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+Affecting both internal and external names:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "xml": {
+ "name": "animal"
+ }
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+If we change the external element but not the internal ones:
+
+```json
+{
+ "animals": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "xml": {
+ "name": "aliens",
+ "wrapped": true
+ }
+ }
+}
+```
+
+```yaml
+animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: aliens
+ wrapped: true
+```
+
+```xml
+
+ value
+ value
+
+```
+
+#### Security Scheme Object
+
+Defines a security scheme that can be used by the operations.
+
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE.
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`.
+description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
+in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
+scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).
+bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
+flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
+openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Security Scheme Object Example
+
+###### Basic Authentication Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "basic"
+}
+```
+
+```yaml
+type: http
+scheme: basic
+```
+
+###### API Key Sample
+
+```json
+{
+ "type": "apiKey",
+ "name": "api_key",
+ "in": "header"
+}
+```
+
+```yaml
+type: apiKey
+name: api_key
+in: header
+```
+
+###### JWT Bearer Sample
+
+```json
+{
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "JWT",
+}
+```
+
+```yaml
+type: http
+scheme: bearer
+bearerFormat: JWT
+```
+
+###### Implicit OAuth2 Sample
+
+```json
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow
+password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow
+clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
+authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+#### OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+##### Fixed Fields
+Field Name | Type | Applies To | Description
+---|:---:|---|---
+authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### OAuth Flow Object Examples
+
+```JSON
+{
+ "type": "oauth2",
+ "flows": {
+ "implicit": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ },
+ "authorizationCode": {
+ "authorizationUrl": "https://example.com/api/oauth/dialog",
+ "tokenUrl": "https://example.com/api/oauth/token",
+ "scopes": {
+ "write:pets": "modify pets in your account",
+ "read:pets": "read your pets"
+ }
+ }
+ }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+ implicit:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+ authorizationCode:
+ authorizationUrl: https://example.com/api/oauth/dialog
+ tokenUrl: https://example.com/api/oauth/token
+ scopes:
+ write:pets: modify pets in your account
+ read:pets: read your pets
+```
+
+#### Security Requirement Object
+
+Lists the required security schemes to execute this operation.
+The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject).
+
+Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
+This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
+
+When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band.
+
+##### Security Requirement Object Examples
+
+###### Non-OAuth2 Security Requirement
+
+```json
+{
+ "api_key": []
+}
+```
+
+```yaml
+api_key: []
+```
+
+###### OAuth2 Security Requirement
+
+```json
+{
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+}
+```
+
+```yaml
+petstore_auth:
+- write:pets
+- read:pets
+```
+
+###### Optional OAuth2 Security
+
+Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object:
+
+```json
+{
+ "security": [
+ {},
+ {
+ "petstore_auth": [
+ "write:pets",
+ "read:pets"
+ ]
+ }
+ ]
+}
+```
+
+```yaml
+security:
+ - {}
+ - petstore_auth:
+ - write:pets
+ - read:pets
+```
+
+### Specification Extensions
+
+While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
+
+The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
+
+Field Pattern | Type | Description
+---|:---:|---
+^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value can be `null`, a primitive, an array or an object.
+
+The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
+
+### Security Filtering
+
+Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation.
+
+The reasoning is to allow an additional layer of access control over the documentation.
+While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization.
+
+Two examples of this:
+
+1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication.
+2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
+
+
+## Appendix A: Revision History
+
+Version | Date | Notes
+--- | --- | ---
+3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0
+3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification
+3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification
+3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3
+3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2
+3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
+3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
+3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
+3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification
+3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification
+2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative
+2.0 | 2014-09-08 | Release of Swagger 2.0
+1.2 | 2014-03-14 | Initial release of the formal document.
+1.1 | 2012-08-22 | Release of Swagger 1.1
+1.0 | 2011-08-10 | First release of the Swagger Specification
\n
\n\n';return g})})();(function(){var b=Handlebars.template,a=Handlebars.templates=Handlebars.templates||{};a.status_code=b(function(e,k,d,j,i){this.compilerInfo=[4,">= 1.0.0"];d=this.merge(d,e.helpers);i=i||{};var g="",c,f="function",h=this.escapeExpression;g+="\n ';if(c=d.signature){c=c.call(k,{hash:{},data:i})}else{c=k.signature;c=typeof c===f?c.apply(k):c}if(c||c===0){g+=c}g+='\n
\n\n \n
\n';if(c=d.sampleJSON){c=c.call(k,{hash:{},data:i})}else{c=k.sampleJSON;c=typeof c===f?c.apply(k):c}g+=h(c)+'");return $(".response_body",$(this.el)).html(escape(B))};y.prototype.showErrorStatus=function(B,A){return A.showStatus(B)};y.prototype.showCompleteStatus=function(B,A){return A.showStatus(B)};y.prototype.formatXml=function(H){var D,G,B,I,N,J,C,A,L,M,F,E,K;A=/(>)(<)(\/*)/g;M=/[ ]*(.*)[ ]+\n/g;D=/(<.+>)(.+\n)/g;H=H.replace(A,"$1\n$2$3").replace(M,"$1\n").replace(D,"$1\n$2");C=0;G="";N=H.split("\n");B=0;I="other";L={"single->single":0,"single->closing":-1,"single->opening":0,"single->other":0,"closing->single":0,"closing->closing":-1,"closing->opening":0,"closing->other":0,"opening->single":1,"opening->closing":0,"opening->opening":1,"opening->other":1,"other->single":0,"other->closing":-1,"other->opening":0,"other->other":0};F=function(T){var P,O,R,V,S,Q,U;Q={single:Boolean(T.match(/<.+\/>/)),closing:Boolean(T.match(/<\/.+>/)),opening:Boolean(T.match(/<[^!?].*>/))};S=((function(){var W;W=[];for(R in Q){U=Q[R];if(U){W.push(R)}}return W})())[0];S=S===void 0?"other":S;P=I+"->"+S;I=S;V="";B+=L[P];V=((function(){var X,Y,W;W=[];for(O=X=0,Y=B;0<=Y?X
"+B+"");$(".response_code",$(this.el)).html("
"+A.status+"");$(".response_body",$(this.el)).html(C);$(".response_headers",$(this.el)).html("
"+JSON.stringify(A.headers,null," ").replace(/\n/g,"");$(".response",$(this.el)).slideDown();$(".response_hider",$(this.el)).show();$(".response_throbber",$(this.el)).hide();return hljs.highlightBlock($(".response_body",$(this.el))[0])};y.prototype.toggleOperationContent=function(){var A;A=$("#"+Docs.escapeResourceName(this.model.parentId)+"_"+this.model.nickname+"_content");if(A.is(":visible")){return Docs.collapseOperation(A)}else{return Docs.expandOperation(A)}};return y})(Backbone.View);p=(function(z){v(y,z);function y(){d=y.__super__.constructor.apply(this,arguments);return d}y.prototype.initialize=function(){};y.prototype.render=function(){var A;A=this.template();$(this.el).html(A(this.model));return this};y.prototype.template=function(){return Handlebars.templates.status_code};return y})(Backbone.View);k=(function(z){v(y,z);function y(){b=y.__super__.constructor.apply(this,arguments);return b}y.prototype.initialize=function(){return Handlebars.registerHelper("isArray",function(B,A){if(B.type.toLowerCase()==="array"||B.allowMultiple){return A.fn(this)}else{return A.inverse(this)}})};y.prototype.render=function(){var G,A,C,F,B,H,E,D;D=this.model.type||this.model.dataType;if(this.model.paramType==="body"){this.model.isBody=true}if(D.toLowerCase()==="file"){this.model.isFile=true}E=this.template();$(this.el).html(E(this.model));B={sampleJSON:this.model.sampleJSON,isParam:true,signature:this.model.signature};if(this.model.sampleJSON){H=new i({model:B,tagName:"div"});$(".model-signature",$(this.el)).append(H.render().el)}else{$(".model-signature",$(this.el)).html(this.model.signature)}A=false;if(this.model.isBody){A=true}G={isParam:A};G.consumes=this.model.consumes;if(A){C=new l({model:G});$(".parameter-content-type",$(this.el)).append(C.render().el)}else{F=new m({model:G});$(".response-content-type",$(this.el)).append(F.render().el)}return this};y.prototype.template=function(){if(this.model.isList){return Handlebars.templates.param_list}else{if(this.options.readOnly){if(this.model.required){return Handlebars.templates.param_readonly_required}else{return Handlebars.templates.param_readonly}}else{if(this.model.required){return Handlebars.templates.param_required}else{return Handlebars.templates.param}}}};return y})(Backbone.View);i=(function(z){v(y,z);function y(){a=y.__super__.constructor.apply(this,arguments);return a}y.prototype.events={"click a.description-link":"switchToDescription","click a.snippet-link":"switchToSnippet","mousedown .snippet":"snippetToTextArea"};y.prototype.initialize=function(){};y.prototype.render=function(){var A;A=this.template();$(this.el).html(A(this.model));this.switchToDescription();this.isParam=this.model.isParam;if(this.isParam){$(".notice",$(this.el)).text("Click to set as parameter value")}return this};y.prototype.template=function(){return Handlebars.templates.signature};y.prototype.switchToDescription=function(A){if(A!=null){A.preventDefault()}$(".snippet",$(this.el)).hide();$(".description",$(this.el)).show();$(".description-link",$(this.el)).addClass("selected");return $(".snippet-link",$(this.el)).removeClass("selected")};y.prototype.switchToSnippet=function(A){if(A!=null){A.preventDefault()}$(".description",$(this.el)).hide();$(".snippet",$(this.el)).show();$(".snippet-link",$(this.el)).addClass("selected");return $(".description-link",$(this.el)).removeClass("selected")};y.prototype.snippetToTextArea=function(A){var B;if(this.isParam){if(A!=null){A.preventDefault()}B=$("textarea",$(this.el.parentNode.parentNode.parentNode));if($.trim(B.val())===""){return B.val(this.model.sampleJSON)}}};return y})(Backbone.View);j=(function(y){v(z,y);function z(){x=z.__super__.constructor.apply(this,arguments);return x}z.prototype.initialize=function(){};z.prototype.render=function(){var A;A=this.template();$(this.el).html(A(this.model));$("label[for=contentType]",$(this.el)).text("Response Content Type");return this};z.prototype.template=function(){return Handlebars.templates.content_type};return z})(Backbone.View);m=(function(y){v(z,y);function z(){w=z.__super__.constructor.apply(this,arguments);return w}z.prototype.initialize=function(){};z.prototype.render=function(){var A;A=this.template();$(this.el).html(A(this.model));$("label[for=responseContentType]",$(this.el)).text("Response Content Type");return this};z.prototype.template=function(){return Handlebars.templates.response_content_type};return z})(Backbone.View);l=(function(z){v(y,z);function y(){c=y.__super__.constructor.apply(this,arguments);return c}y.prototype.initialize=function(){};y.prototype.render=function(){var A;A=this.template();$(this.el).html(A(this.model));$("label[for=parameterContentType]",$(this.el)).text("Parameter content type:");return this};y.prototype.template=function(){return Handlebars.templates.parameter_content_type};return y})(Backbone.View)}).call(this); \ No newline at end of file diff --git a/fixtures/v1.2/helloworld/static/README.md b/fixtures/v1.2/helloworld/static/README.md deleted file mode 100644 index 1b365c4728..0000000000 --- a/fixtures/v1.2/helloworld/static/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Static Hello World Sample Files - -This sample project provides the static files to be hosted in your web server, following the Hello World sample described in the [wiki](https://github.com/swagger-api/swagger-spec/wiki/Hello-World-Sample). diff --git a/fixtures/v1.2/helloworld/static/api-docs b/fixtures/v1.2/helloworld/static/api-docs deleted file mode 100644 index 6f2f3cb95b..0000000000 --- a/fixtures/v1.2/helloworld/static/api-docs +++ /dev/null @@ -1,9 +0,0 @@ -{ - "swaggerVersion": "1.2", - "apis": [ - { - "path": "http://localhost:8000/listings/greetings", - "description": "Generating greetings in our application." - } - ] -} diff --git a/fixtures/v1.2/helloworld/static/listings/greetings b/fixtures/v1.2/helloworld/static/listings/greetings deleted file mode 100644 index 78cabafd3e..0000000000 --- a/fixtures/v1.2/helloworld/static/listings/greetings +++ /dev/null @@ -1,26 +0,0 @@ -{ - "swaggerVersion": "1.2", - "basePath": "http://localhost:8000/greetings", - "apis": [ - { - "path": "/hello/{subject}", - "operations": [ - { - "method": "GET", - "summary": "Greet our subject with hello!", - "type": "string", - "nickname": "helloSubject", - "parameters": [ - { - "name": "subject", - "description": "The subject to be greeted.", - "required": true, - "type": "string", - "paramType": "path" - } - ] - } - ] - } - ] -} diff --git a/fixtures/v2.0/json/general/basicInfoObject.json b/fixtures/v2.0/json/general/basicInfoObject.json deleted file mode 100644 index f5fff64a77..0000000000 --- a/fixtures/v2.0/json/general/basicInfoObject.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "title": "Swagger Sample App", - "description": "This is a sample server Petstore server.", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "API Support", - "url": "http://www.swagger.io/support", - "email": "support@swagger.io" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "1.0.1" - } diff --git a/fixtures/v2.0/json/general/externalDocs.json b/fixtures/v2.0/json/general/externalDocs.json deleted file mode 100644 index 82a74b602d..0000000000 --- a/fixtures/v2.0/json/general/externalDocs.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "description": "Find more info here", - "url": "https://swagger.io" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/general/minimalInfoObject.json b/fixtures/v2.0/json/general/minimalInfoObject.json deleted file mode 100644 index 05ce00a90f..0000000000 --- a/fixtures/v2.0/json/general/minimalInfoObject.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "title": "Swagger Sample App", - "version": "1.0.1" - } diff --git a/fixtures/v2.0/json/general/negative/negativeExternalDocs.json b/fixtures/v2.0/json/general/negative/negativeExternalDocs.json deleted file mode 100644 index 54e9db3c9a..0000000000 --- a/fixtures/v2.0/json/general/negative/negativeExternalDocs.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "description": "Find more info here" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/general/negative/negativeInfoObject.json b/fixtures/v2.0/json/general/negative/negativeInfoObject.json deleted file mode 100644 index d06b8930b9..0000000000 --- a/fixtures/v2.0/json/general/negative/negativeInfoObject.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "description": "This is a sample server Petstore server.", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "API Support", - "url": "http://www.swagger.io/support", - "email": "support@swagger.io" - }, - "license": { - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - } - } diff --git a/fixtures/v2.0/json/models/modelWithArrayRef.json b/fixtures/v2.0/json/models/modelWithArrayRef.json deleted file mode 100644 index f52eaedb02..0000000000 --- a/fixtures/v2.0/json/models/modelWithArrayRef.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "required": [ - "id" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "children": { - "type": "array", - "items": { - "$ref": "#/definitions/Person" - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithComposition.json b/fixtures/v2.0/json/models/modelWithComposition.json deleted file mode 100644 index 3a01b0b1c8..0000000000 --- a/fixtures/v2.0/json/models/modelWithComposition.json +++ /dev/null @@ -1,86 +0,0 @@ -{ - "Pet": { - "discriminator": "petType", - "properties": { - "name": { - "type": "string" - }, - "petType": { - "type": "string" - } - }, - "required": [ - "name", - "petType" - ] - }, - "Cat": { - "description": "A representation of a cat", - "allOf": [ - { - "$ref": "#/definitions/Pet" - }, - { - "properties": { - "huntingSkill": { - "type": "string", - "description": "The measured skill for hunting", - "default": "lazy", - "enum": [ - "clueless", - "lazy", - "adventurous", - "aggressive" - ] - } - }, - "required": [ - "huntingSkill" - ] - } - ] - }, - "Dog": { - "description": "A representation of a dog", - "allOf": [ - { - "$ref": "#/definitions/Pet" - }, - { - "properties": { - "packSize": { - "type": "integer", - "format": "int32", - "description": "the size of the pack the dog is from", - "default": 0, - "minimum": 0 - } - }, - "required": [ - "packSize" - ] - } - ] - }, - "Fish": { - "description": "A representation of a fish", - "allOf": [ - { - "$ref": "#/definitions/Pet" - }, - { - "properties": { - "fins": { - "type": "integer", - "format": "int32", - "description": "count of fins", - "minimum": 0 - } - }, - "required": [ - "fins" - ] - } - ] - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithDateTimeMap.json b/fixtures/v2.0/json/models/modelWithDateTimeMap.json deleted file mode 100644 index a5ebdf9b29..0000000000 --- a/fixtures/v2.0/json/models/modelWithDateTimeMap.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "true", - "additionalProperties": { - "type": "string", - "format": "date-time" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithExamples.json b/fixtures/v2.0/json/models/modelWithExamples.json deleted file mode 100644 index 147bd5757f..0000000000 --- a/fixtures/v2.0/json/models/modelWithExamples.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - }, - "Dog": { - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "example": { - "name": "Puma", - "id": 1 - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithInt32Map.json b/fixtures/v2.0/json/models/modelWithInt32Map.json deleted file mode 100644 index b4597e846d..0000000000 --- a/fixtures/v2.0/json/models/modelWithInt32Map.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "This is a Map[String, Integer]", - "additionalProperties": { - "type": "integer", - "format": "int32" - } -} diff --git a/fixtures/v2.0/json/models/modelWithInt64Map.json b/fixtures/v2.0/json/models/modelWithInt64Map.json deleted file mode 100644 index 5160f21c4e..0000000000 --- a/fixtures/v2.0/json/models/modelWithInt64Map.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "true", - "additionalProperties": { - "type": "integer", - "format": "int64" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithMultipleProperties.json b/fixtures/v2.0/json/models/modelWithMultipleProperties.json deleted file mode 100644 index dba5e64abd..0000000000 --- a/fixtures/v2.0/json/models/modelWithMultipleProperties.json +++ /dev/null @@ -1,67 +0,0 @@ -{ - "description": "true", - "properties": { - "booleanValue": { - "type": "boolean" - }, - "byteValue": { - "type": "string", - "format": "byte" - }, - "dateTimeValue": { - "type": "string", - "format": "date-time" - }, - "int32Value": { - "type": "integer", - "format": "int32" - }, - "int64Value": { - "type": "integer", - "format": "int64" - }, - "stringValue": { - "type": "string" - }, - "booleanArrayValue": { - "type": "array", - "items": { - "type": "boolean" - } - }, - "byteArrayValue": { - "type": "array", - "items": { - "type": "string", - "format": "byte" - } - }, - "dateTimeArrayValue": { - "type": "array", - "items": { - "type": "string", - "format": "date-time" - } - }, - "int32ArrayValue": { - "type": "array", - "items": { - "type": "integer", - "format": "int32" - } - }, - "int64ArrayValue": { - "type": "array", - "items": { - "type": "integer", - "format": "int64" - } - }, - "stringArrayValue": { - "type": "array", - "items": { - "type": "string" - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithPrimitiveArray.json b/fixtures/v2.0/json/models/modelWithPrimitiveArray.json deleted file mode 100644 index bc1a8e1740..0000000000 --- a/fixtures/v2.0/json/models/modelWithPrimitiveArray.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "required": [ - "id" - ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "childrensAges": { - "type": "array", - "items": { - "type": "integer", - "format": "int32" - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithStringProperty.json b/fixtures/v2.0/json/models/modelWithStringProperty.json deleted file mode 100644 index 53b4fe1d7c..0000000000 --- a/fixtures/v2.0/json/models/modelWithStringProperty.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "description": "true", - "properties": { - "name": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/modelWithXmlAttributes.json b/fixtures/v2.0/json/models/modelWithXmlAttributes.json deleted file mode 100644 index 1aed1a9f73..0000000000 --- a/fixtures/v2.0/json/models/modelWithXmlAttributes.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "description": "this model serves xml and json structures", - "xml": { - "name": "XMLModel" - }, - "properties": { - "id": { - "type": "integer", - "format": "int64", - "xml": { - "attribute": true, - "namespace": "ns1", - "prefix": "urn1" - } - }, - "items": { - "type": "array", - "items": { - "type": "string" - }, - "xml": { - "wrapped": true - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/models.json b/fixtures/v2.0/json/models/models.json deleted file mode 100644 index 2d47051e21..0000000000 --- a/fixtures/v2.0/json/models/models.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/multipleModels.json b/fixtures/v2.0/json/models/multipleModels.json deleted file mode 100644 index f62438ea87..0000000000 --- a/fixtures/v2.0/json/models/multipleModels.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "Pet": { - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - }, - "Dog": { - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithBooleanArray.json b/fixtures/v2.0/json/models/properties/propertyWithBooleanArray.json deleted file mode 100644 index e7ae99b077..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithBooleanArray.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "type": "array", - "items": { - "type": "boolean" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithByteArray.json b/fixtures/v2.0/json/models/properties/propertyWithByteArray.json deleted file mode 100644 index a6cb13c18b..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithByteArray.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "array", - "items": { - "type": "string", - "format": "byte" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithComplexArray.json b/fixtures/v2.0/json/models/properties/propertyWithComplexArray.json deleted file mode 100644 index 0f2b9f57fe..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithComplexArray.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "type": "array", - "items": { - "$ref": "#/definitions/ComplexType" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithDateTimeArray.json b/fixtures/v2.0/json/models/properties/propertyWithDateTimeArray.json deleted file mode 100644 index 8b1077316d..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithDateTimeArray.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "array", - "items": { - "type": "string", - "format": "date-time" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithInt32Array.json b/fixtures/v2.0/json/models/properties/propertyWithInt32Array.json deleted file mode 100644 index 5aae819cae..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithInt32Array.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "array", - "items": { - "type": "integer", - "format": "int32" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithInt64Array.json b/fixtures/v2.0/json/models/properties/propertyWithInt64Array.json deleted file mode 100644 index 5b1f551595..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithInt64Array.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "type": "array", - "items": { - "type": "integer", - "format": "int64" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/propertyWithStringArray.json b/fixtures/v2.0/json/models/properties/propertyWithStringArray.json deleted file mode 100644 index 7936520d79..0000000000 --- a/fixtures/v2.0/json/models/properties/propertyWithStringArray.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "type": "array", - "items": { - "type": "string" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleBooleanProperty.json b/fixtures/v2.0/json/models/properties/simpleBooleanProperty.json deleted file mode 100644 index 610470e057..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleBooleanProperty.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "type": "boolean", - "description": "a boolean", - "readOnly": true -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleByteProperty.json b/fixtures/v2.0/json/models/properties/simpleByteProperty.json deleted file mode 100644 index 74fc007f75..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleByteProperty.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "type": "string", - "format": "byte" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleDateTimeProperty.json b/fixtures/v2.0/json/models/properties/simpleDateTimeProperty.json deleted file mode 100644 index a154c6b388..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleDateTimeProperty.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "type": "string", - "format": "date-time" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleInt32Property.json b/fixtures/v2.0/json/models/properties/simpleInt32Property.json deleted file mode 100644 index b436c52c79..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleInt32Property.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "type": "integer", - "format": "int32" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleInt64Property.json b/fixtures/v2.0/json/models/properties/simpleInt64Property.json deleted file mode 100644 index 1f3419620e..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleInt64Property.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "type": "integer", - "format": "int64" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/models/properties/simpleStringProperty.json b/fixtures/v2.0/json/models/properties/simpleStringProperty.json deleted file mode 100644 index 28ac6e8648..0000000000 --- a/fixtures/v2.0/json/models/properties/simpleStringProperty.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "type": "string" -} diff --git a/fixtures/v2.0/json/resources/cascadingSchemes.json b/fixtures/v2.0/json/resources/cascadingSchemes.json deleted file mode 100644 index dc2a00e1d3..0000000000 --- a/fixtures/v2.0/json/resources/cascadingSchemes.json +++ /dev/null @@ -1,98 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{petId}": { - "get": { - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - }, - "schemes": [ "https" ] - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/commonParameters.json b/fixtures/v2.0/json/resources/commonParameters.json deleted file mode 100644 index 9e152c260b..0000000000 --- a/fixtures/v2.0/json/resources/commonParameters.json +++ /dev/null @@ -1,100 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to use", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "get": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/multipleMimeTypes.json b/fixtures/v2.0/json/resources/multipleMimeTypes.json deleted file mode 100644 index 4638051ecb..0000000000 --- a/fixtures/v2.0/json/resources/multipleMimeTypes.json +++ /dev/null @@ -1,109 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "text/plain; charset=utf-8", - "application/json", - "application/vnd.github+json", - "application/vnd.github.v3+json", - "application/vnd.github.v3.raw+json", - "application/vnd.github.v3.text+json", - "application/vnd.github.v3.html+json", - "application/vnd.github.v3.full+json", - "application/vnd.github.v3.diff", - "application/vnd.github.v3.patch" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to use", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "get": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/operations/operationWithTags.json b/fixtures/v2.0/json/resources/operations/operationWithTags.json deleted file mode 100644 index 34323ecde5..0000000000 --- a/fixtures/v2.0/json/resources/operations/operationWithTags.json +++ /dev/null @@ -1,30 +0,0 @@ -{ - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "tags": [ "foo", "bar"], - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "a pet to be returned", - "schema": {"$ref": "#/definitions/Pet"} - }, - "default": { - "description": "Unexpected error", - "schema": {"$ref": "#/definitions/ErrorModel"} - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/operations/stringPathAndBoolQueryParamResource.json b/fixtures/v2.0/json/resources/operations/stringPathAndBoolQueryParamResource.json deleted file mode 100644 index 4c5ed7606f..0000000000 --- a/fixtures/v2.0/json/resources/operations/stringPathAndBoolQueryParamResource.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "integer", - "format": "int64" - }, - { - "name": "includeDetails", - "in": "query", - "description": "include details in response", - "required": true, - "type": "boolean" - } - ], - "responses": { - "200": { - "description": "a pet to be returned", - "schema": {"$ref": "#/definitions/Pet"} - }, - "default": { - "description": "Unexpected error", - "schema": {"$ref": "#/definitions/ErrorModel"} - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/operations/stringPathParamResource.json b/fixtures/v2.0/json/resources/operations/stringPathParamResource.json deleted file mode 100644 index 138ea859be..0000000000 --- a/fixtures/v2.0/json/resources/operations/stringPathParamResource.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "integer", - "format": "int64" - } - ], - "responses": { - "200": { - "description": "fun", - "schema": {"$ref": "#/definitions/Pet"} - }, - "400": { - "description": "Invalid ID supplied <= this is purely for documentation", - "schema": {"$ref": "#/definitions/ErrorModel"} - }, - "default": { - "description": "Unexpected error", - "schema": {"$ref": "#/definitions/ErrorModel"} - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/bodyComplexArrayParameter.json b/fixtures/v2.0/json/resources/parameters/bodyComplexArrayParameter.json deleted file mode 100644 index 62076b764b..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyComplexArrayParameter.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "name": "user", - "in": "body", - "description": "user to add to the system", - "required": true, - "schema": { - "type": "array", - "items": { - "type": "string" - } - } -} diff --git a/fixtures/v2.0/json/resources/parameters/bodyComplexInlineParameter.json b/fixtures/v2.0/json/resources/parameters/bodyComplexInlineParameter.json deleted file mode 100644 index 20cacfbb6e..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyComplexInlineParameter.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "name": "user", - "in": "body", - "description": "user to add to the system", - "required": true, - "schema": { - "type": "object", - "required": [ "name", "id" ], - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - }, - "keys": { - "type": "array", - "items": { - "type": "integer" - } - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/bodyComplexParameter.json b/fixtures/v2.0/json/resources/parameters/bodyComplexParameter.json deleted file mode 100644 index baaefae461..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyComplexParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "user", - "in": "body", - "description": "user to add to the system", - "required": true, - "schema": { - "$ref": "#/definitions/User" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/bodyInt64Parameter.json b/fixtures/v2.0/json/resources/parameters/bodyInt64Parameter.json deleted file mode 100644 index 5bd668b811..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyInt64Parameter.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "name": "id", - "in": "body", - "description": "id to add", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/bodyStringArrayParameter.json b/fixtures/v2.0/json/resources/parameters/bodyStringArrayParameter.json deleted file mode 100644 index 535a3056dc..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyStringArrayParameter.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "name": "user", - "in": "body", - "description": "user to add to the system", - "required": true, - "schema": { - "type": "array", - "items": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/bodyStringParameter.json b/fixtures/v2.0/json/resources/parameters/bodyStringParameter.json deleted file mode 100644 index 499435a5b6..0000000000 --- a/fixtures/v2.0/json/resources/parameters/bodyStringParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "user", - "in": "body", - "description": "user to add to the system", - "required": true, - "schema": { - "type": "string" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/formDataInt64Parameter.json b/fixtures/v2.0/json/resources/parameters/formDataInt64Parameter.json deleted file mode 100644 index c00176cb42..0000000000 --- a/fixtures/v2.0/json/resources/parameters/formDataInt64Parameter.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "id", - "in": "formData", - "description": "username to fetch", - "required": true, - "type": "integer", - "format": "int64" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/formDataStringArrayParameter.json b/fixtures/v2.0/json/resources/parameters/formDataStringArrayParameter.json deleted file mode 100644 index 9d06ef4652..0000000000 --- a/fixtures/v2.0/json/resources/parameters/formDataStringArrayParameter.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "name": "user", - "in": "formData", - "description": "user to add to the system", - "required": true, - "type": "array", - "items": { - "type": "string" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/formDataStringParameter.json b/fixtures/v2.0/json/resources/parameters/formDataStringParameter.json deleted file mode 100644 index 98d66e63d8..0000000000 --- a/fixtures/v2.0/json/resources/parameters/formDataStringParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "firstName", - "in": "formData", - "description": "users first name", - "required": true, - "type": "string" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/headerInt64ArrayParameter.json b/fixtures/v2.0/json/resources/parameters/headerInt64ArrayParameter.json deleted file mode 100644 index 81c8f2f131..0000000000 --- a/fixtures/v2.0/json/resources/parameters/headerInt64ArrayParameter.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "name": "token", - "in": "header", - "description": "token to be passed as a header", - "required": true, - "type": "array", - "items": { - "type": "integer", - "format": "int64" - }, - "collectionFormat": "csv" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/headerStringArrayParameter.json b/fixtures/v2.0/json/resources/parameters/headerStringArrayParameter.json deleted file mode 100644 index d6b134f936..0000000000 --- a/fixtures/v2.0/json/resources/parameters/headerStringArrayParameter.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "name": "token", - "in": "header", - "description": "token to be passed as a header", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/headerStringParameter.json b/fixtures/v2.0/json/resources/parameters/headerStringParameter.json deleted file mode 100644 index d10051ed23..0000000000 --- a/fixtures/v2.0/json/resources/parameters/headerStringParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "token", - "in": "header", - "description": "token to be passed as a header", - "required": true, - "type": "string" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/bodyFileParameter.json b/fixtures/v2.0/json/resources/parameters/negative/bodyFileParameter.json deleted file mode 100644 index 9fcc71f940..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/bodyFileParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "username", - "in": "body", - "description": "username to fetch", - "required": true, - "schema": { - "type": "file" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/bodyNonSchemaParameter.json b/fixtures/v2.0/json/resources/parameters/negative/bodyNonSchemaParameter.json deleted file mode 100644 index dc572443bb..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/bodyNonSchemaParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "body", - "description": "username to fetch", - "required": true, - "type": "string" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/formDataComplexParameter.json b/fixtures/v2.0/json/resources/parameters/negative/formDataComplexParameter.json deleted file mode 100644 index eb93d72489..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/formDataComplexParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "firstName", - "in": "formData", - "description": "users first name", - "required": true, - "$ref": "#/definitions/Nothing" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/formDataSchemaParameter.json b/fixtures/v2.0/json/resources/parameters/negative/formDataSchemaParameter.json deleted file mode 100644 index 6e9c5d16a5..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/formDataSchemaParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "firstName", - "in": "formData", - "description": "users first name", - "required": true, - "schema": { - "$ref": "#/definitions/Nothing" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/headerComplexParameter.json b/fixtures/v2.0/json/resources/parameters/negative/headerComplexParameter.json deleted file mode 100644 index 327de45492..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/headerComplexParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "firstName", - "in": "header", - "description": "users first name", - "required": true, - "$ref": "#/definitions/Nothing" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/headerFileParameter.json b/fixtures/v2.0/json/resources/parameters/negative/headerFileParameter.json deleted file mode 100644 index 902e11244b..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/headerFileParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "header", - "description": "username to fetch", - "required": true, - "type": "file" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/headerSchemaParameter.json b/fixtures/v2.0/json/resources/parameters/negative/headerSchemaParameter.json deleted file mode 100644 index b57bb9f85c..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/headerSchemaParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "firstName", - "in": "header", - "description": "users first name", - "required": true, - "schema": { - "$ref": "#/definitions/Nothing" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/pathComplexParameter.json b/fixtures/v2.0/json/resources/parameters/negative/pathComplexParameter.json deleted file mode 100644 index 3c0d3d3542..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/pathComplexParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "firstName", - "in": "path", - "description": "users first name", - "required": true, - "$ref": "#/definitions/Nothing" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/pathFileParameter.json b/fixtures/v2.0/json/resources/parameters/negative/pathFileParameter.json deleted file mode 100644 index 38df4f713e..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/pathFileParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "path", - "description": "username to fetch", - "required": true, - "type": "file" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/pathNonRequiredStringParameter.json b/fixtures/v2.0/json/resources/parameters/negative/pathNonRequiredStringParameter.json deleted file mode 100644 index af68e6fdc2..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/pathNonRequiredStringParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "path", - "description": "username to fetch", - "required": false, - "type": "string" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/pathSchemaParameter.json b/fixtures/v2.0/json/resources/parameters/negative/pathSchemaParameter.json deleted file mode 100644 index be00dbb8be..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/pathSchemaParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "firstName", - "in": "path", - "description": "users first name", - "required": true, - "schema": { - "$ref": "#/definitions/Nothing" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/queryComplexParameter.json b/fixtures/v2.0/json/resources/parameters/negative/queryComplexParameter.json deleted file mode 100644 index 80fe3029ed..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/queryComplexParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "firstName", - "in": "query", - "description": "users first name", - "required": true, - "$ref": "#/definitions/Nothing" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/queryFileParameter.json b/fixtures/v2.0/json/resources/parameters/negative/queryFileParameter.json deleted file mode 100644 index e69db2b619..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/queryFileParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "query", - "description": "username to fetch", - "required": true, - "type": "file" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/negative/querySchemaParameter.json b/fixtures/v2.0/json/resources/parameters/negative/querySchemaParameter.json deleted file mode 100644 index 5357417ce5..0000000000 --- a/fixtures/v2.0/json/resources/parameters/negative/querySchemaParameter.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "firstName", - "in": "query", - "description": "users first name", - "required": true, - "schema": { - "$ref": "#/definitions/Nothing" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/pathInt64Parameter.json b/fixtures/v2.0/json/resources/parameters/pathInt64Parameter.json deleted file mode 100644 index 47bf2e0b92..0000000000 --- a/fixtures/v2.0/json/resources/parameters/pathInt64Parameter.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "id", - "in": "path", - "description": "username to fetch", - "required": true, - "type": "integer", - "format": "int64" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/pathStringArrayParameter.json b/fixtures/v2.0/json/resources/parameters/pathStringArrayParameter.json deleted file mode 100644 index 6da46aa5d7..0000000000 --- a/fixtures/v2.0/json/resources/parameters/pathStringArrayParameter.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "name": "usernames", - "in": "path", - "description": "usernames to pass", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/pathStringParameter.json b/fixtures/v2.0/json/resources/parameters/pathStringParameter.json deleted file mode 100644 index 0ac9c6f076..0000000000 --- a/fixtures/v2.0/json/resources/parameters/pathStringParameter.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "username", - "in": "path", - "description": "username to fetch", - "required": true, - "type": "string" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/queryInt64ArrayParameter.json b/fixtures/v2.0/json/resources/parameters/queryInt64ArrayParameter.json deleted file mode 100644 index 59b557a6f6..0000000000 --- a/fixtures/v2.0/json/resources/parameters/queryInt64ArrayParameter.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "name": "id", - "in": "query", - "description": "ID of the object to fetch", - "required": true, - "type": "array", - "items": { - "type": "integer", - "format": "int64" - }, - "collectionFormat": "csv" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/parameters/queryInt64Parameter.json b/fixtures/v2.0/json/resources/parameters/queryInt64Parameter.json deleted file mode 100644 index fde2d3badb..0000000000 --- a/fixtures/v2.0/json/resources/parameters/queryInt64Parameter.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "name": "id", - "in": "query", - "description": "ID of the object to fetch", - "required": true, - "type": "integer", - "format": "int64" -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/resourceWithExamplePayload.json b/fixtures/v2.0/json/resources/resourceWithExamplePayload.json deleted file mode 100644 index feb50c1c3d..0000000000 --- a/fixtures/v2.0/json/resources/resourceWithExamplePayload.json +++ /dev/null @@ -1,114 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{petId}": { - "get": { - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - }, - "examples": { - "application/json": { - "id": 9, - "category": { - "name": "domestic" - }, - "name": "monster", - "tags": [ - { - "name": "for sale" - } - ], - "status": "alive" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "example": "cat" - }, - "tag": { - "type": "string", - "example": "for sale" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json b/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json deleted file mode 100644 index 81a81d4b8c..0000000000 --- a/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json +++ /dev/null @@ -1,62 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{petId}": { - "$ref": "https://raw.githubusercontent.com/swagger-api/swagger-spec/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json" - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json b/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json deleted file mode 100644 index a79ee51499..0000000000 --- a/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json +++ /dev/null @@ -1,38 +0,0 @@ -{ - "get": { - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#/definitions/Pet" - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#/definitions/ErrorModel" - } - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/resourceWithRelativeHost.json b/fixtures/v2.0/json/resources/resourceWithRelativeHost.json deleted file mode 100644 index fcebbfa4f6..0000000000 --- a/fixtures/v2.0/json/resources/resourceWithRelativeHost.json +++ /dev/null @@ -1,99 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to use", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "get": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/reusableParameters.json b/fixtures/v2.0/json/resources/reusableParameters.json deleted file mode 100644 index 8eb81a0946..0000000000 --- a/fixtures/v2.0/json/resources/reusableParameters.json +++ /dev/null @@ -1,105 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{id}": { - "get": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "getPetsById", - "parameters": [ - { "$ref": "#/parameters/skipParam" }, - { "$ref": "#/parameters/limitParam" } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "parameters": { - "skipParam": { - "name": "skip", - "in": "query", - "description": "number of items to skip", - "required": true, - "type": "integer", - "format": "int32" - }, - "limitParam": { - "name": "limit", - "in": "query", - "description": "max records to return", - "required": true, - "type": "integer", - "format": "int32" - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/securityExample.json b/fixtures/v2.0/json/resources/securityExample.json deleted file mode 100644 index 5d159c395d..0000000000 --- a/fixtures/v2.0/json/resources/securityExample.json +++ /dev/null @@ -1,181 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "security": [ - { - "githubAccessCode": [ "user", "gist" ] - }, - { - "internalApiKey": [] - } - ], - "paths": { - "/pets/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of pet to use", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "get": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "getPetsById", - "security": [ - { - "githubAuth":[ - "user:read", - "user:write" - ] - }, - { - "internalApiKey": [] - } - ], - "produces": [ - "application/json", - "text/html" - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/Pet" - } - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "securityDefinitions": { - "githubAccessCode": { - "type": "oauth2", - "scopes": { - "user": "Grants read/write access to profile info only. Note that this scope includes user:email and user:follow.", - "user:email": "Grants read access to a user’s email addresses.", - "user:follow": "Grants access to follow or unfollow other users.", - "public_repo": "Grants read/write access to code, commit statuses, and deployment statuses for public repositories and organizations.", - "repo": "Grants read/write access to code, commit statuses, and deployment statuses for public and private repositories and organizations.", - "repo_deployment": "Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code.", - "repo:status": "Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code.", - "delete_repo": "Grants access to delete adminable repositories.", - "notifications": "Grants read access to a user’s notifications. repo also provides this access.", - "gist": "Grants write access to gists.", - "read:repo_hook": "Grants read and ping access to hooks in public or private repositories.", - "write:repo_hook": "Grants read, write, and ping access to hooks in public or private repositories.", - "admin:repo_hook": "Grants read, write, ping, and delete access to hooks in public or private repositories.", - "read:org": "Read-only access to organization, teams, and membership.", - "write:org": "Publicize and unpublicize organization membership.", - "admin:org": "Fully manage organization, teams, and memberships.", - "read:public_key": "List and view details for public keys.", - "write:public_key": "Create, list, and view details for public keys.", - "admin:public_key": "Fully manage public keys." - }, - "flow": "accessCode", - "authorizationUrl": "https://github.com/login/oauth/authorize", - "tokenUrl": "https://github.com/login/oauth/access_token" - }, - "petstoreImplicit": { - "type": "oauth2", - "scopes": { - "user": "Grants read/write access to profile info only. Note that this scope includes user:email and user:follow.", - "user:email": "Grants read access to a user’s email addresses.", - "user:follow": "Grants access to follow or unfollow other users.", - "public_repo": "Grants read/write access to code, commit statuses, and deployment statuses for public repositories and organizations.", - "repo": "Grants read/write access to code, commit statuses, and deployment statuses for public and private repositories and organizations.", - "repo_deployment": "Grants access to deployment statuses for public and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, without granting access to the code.", - "repo:status": "Grants read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code.", - "delete_repo": "Grants access to delete adminable repositories.", - "notifications": "Grants read access to a user’s notifications. repo also provides this access.", - "gist": "Grants write access to gists.", - "read:repo_hook": "Grants read and ping access to hooks in public or private repositories.", - "write:repo_hook": "Grants read, write, and ping access to hooks in public or private repositories.", - "admin:repo_hook": "Grants read, write, ping, and delete access to hooks in public or private repositories.", - "read:org": "Read-only access to organization, teams, and membership.", - "write:org": "Publicize and unpublicize organization membership.", - "admin:org": "Fully manage organization, teams, and memberships.", - "read:public_key": "List and view details for public keys.", - "write:public_key": "Create, list, and view details for public keys.", - "admin:public_key": "Fully manage public keys." - }, - "flow": "implicit", - "authorizationUrl": "http://petstore.swagger.io/oauth/dialog" - }, - "internalApiKey": { - "type": "apiKey", - "in": "header", - "name": "api_key" - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ - "code", - "message" - ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/resources/stringPathParamResource.json b/fixtures/v2.0/json/resources/stringPathParamResource.json deleted file mode 100644 index 6d87a817fd..0000000000 --- a/fixtures/v2.0/json/resources/stringPathParamResource.json +++ /dev/null @@ -1,97 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "/pets/{petId}": { - "get": { - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/taggedResource.json b/fixtures/v2.0/json/resources/taggedResource.json deleted file mode 100644 index 83018cabb3..0000000000 --- a/fixtures/v2.0/json/resources/taggedResource.json +++ /dev/null @@ -1,112 +0,0 @@ -{ - "swagger": "2.0", - "x-swagger": { - "addAnythingYouWant": true - }, - "info": { - "x-swagger-info": "this is an example", - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "tags": [ - { - "name": "pets" - } - ], - "paths": { - "x-swagger-path-info": "vendor info", - "/pets": { - "x-vendor-method": {}, - "get": { - "x-vendor-operation-property": {}, - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "x-vendor-parameter-property": {}, - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "x-vendor-operation-response-property": {}, - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "x-vendor-model-property": {}, - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/resources/vendorExtensionExamples.json b/fixtures/v2.0/json/resources/vendorExtensionExamples.json deleted file mode 100644 index 40678f4fd8..0000000000 --- a/fixtures/v2.0/json/resources/vendorExtensionExamples.json +++ /dev/null @@ -1,107 +0,0 @@ -{ - "swagger": "2.0", - "x-swagger": { - "addAnythingYouWant": true - }, - "info": { - "x-swagger-info": "this is an example", - "version": "1.0.9-abcd", - "title": "Swagger Sample API", - "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", - "termsOfService": "http://swagger.io/terms/", - "contact": { - "name": "Swagger API Team", - "url": "http://swagger.io" - }, - "license": { - "name": "Creative Commons 4.0 International", - "url": "http://creativecommons.org/licenses/by/4.0/" - } - }, - "host": "my.api.com", - "basePath": "/v1", - "schemes": [ - "http", - "https" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json", - "application/xml" - ], - "paths": { - "x-swagger-path-info": "vendor info", - "/pets": { - "x-vendor-method": {}, - "get": { - "x-vendor-operation-property": {}, - "description": "Returns a pet based on ID", - "summary": "Find pet by ID", - "operationId": "getPetsById", - "produces": [ - "application/json", - "text/html" - ], - "parameters": [ - { - "x-vendor-parameter-property": {}, - "name": "petId", - "in": "path", - "description": "ID of pet that needs to be fetched", - "required": true, - "type": "array", - "items": { - "type": "string" - }, - "collectionFormat": "csv" - } - ], - "responses": { - "x-vendor-operation-response-property": {}, - "200": { - "description": "pet response", - "schema": { - "$ref": "#/definitions/Pet" - } - }, - "default": { - "description": "error payload", - "schema": { - "$ref": "#/definitions/ErrorModel" - } - } - } - } - } - }, - "definitions": { - "Pet": { - "x-vendor-model-property": {}, - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "tag": { - "type": "string" - } - } - }, - "ErrorModel": { - "required": [ "code", "message" ], - "properties": { - "code": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - } -} diff --git a/fixtures/v2.0/json/responses/complexArrayResponse.json b/fixtures/v2.0/json/responses/complexArrayResponse.json deleted file mode 100644 index 6825c76cac..0000000000 --- a/fixtures/v2.0/json/responses/complexArrayResponse.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "description": "A complex object array response", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/VeryComplexType" - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/dateTimeResponse.json b/fixtures/v2.0/json/responses/dateTimeResponse.json deleted file mode 100644 index 77fe8d442a..0000000000 --- a/fixtures/v2.0/json/responses/dateTimeResponse.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "A date-time response", - "schema": { - "type": "string", - "format": "date-time" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/int32Response.json b/fixtures/v2.0/json/responses/int32Response.json deleted file mode 100644 index b9470c8f23..0000000000 --- a/fixtures/v2.0/json/responses/int32Response.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "A simple string response", - "schema": { - "type": "integer", - "format": "int32" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/int64Response.json b/fixtures/v2.0/json/responses/int64Response.json deleted file mode 100644 index 16a4d1c1c7..0000000000 --- a/fixtures/v2.0/json/responses/int64Response.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "description": "A simple string response", - "schema": { - "type": "integer", - "format": "int64" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/multipleResponses.json b/fixtures/v2.0/json/responses/multipleResponses.json deleted file mode 100644 index b7c51544e6..0000000000 --- a/fixtures/v2.0/json/responses/multipleResponses.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "200": { - "description": "simple string response", - "schema": { - "type": "string" - } - }, - "201": { - "description": "object created" - }, - "default": { - "description": "oops", - "schema": { - "type": "integer", - "format": "int32" - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/negative/noResponses.json b/fixtures/v2.0/json/responses/negative/noResponses.json deleted file mode 100644 index e135aa931a..0000000000 --- a/fixtures/v2.0/json/responses/negative/noResponses.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "x-test": {} -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/negative/noResponsesWithVendorExtension.json b/fixtures/v2.0/json/responses/negative/noResponsesWithVendorExtension.json deleted file mode 100644 index 7a73a41bfd..0000000000 --- a/fixtures/v2.0/json/responses/negative/noResponsesWithVendorExtension.json +++ /dev/null @@ -1,2 +0,0 @@ -{ -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/stringArrayResponse.json b/fixtures/v2.0/json/responses/stringArrayResponse.json deleted file mode 100644 index 4640ea04ba..0000000000 --- a/fixtures/v2.0/json/responses/stringArrayResponse.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "description": "A string array response", - "schema": { - "type": "array", - "items": { - "type": "string" - } - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/stringResponse.json b/fixtures/v2.0/json/responses/stringResponse.json deleted file mode 100644 index f794027371..0000000000 --- a/fixtures/v2.0/json/responses/stringResponse.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "description": "A simple string response", - "schema": { - "type": "string" - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/stringResponseWithHeader.json b/fixtures/v2.0/json/responses/stringResponseWithHeader.json deleted file mode 100644 index 7bdae4d35d..0000000000 --- a/fixtures/v2.0/json/responses/stringResponseWithHeader.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "description": "A simple string response", - "schema": { - "type": "string" - }, - "headers": { - "is-dog": {"type": "boolean"}, - "is-cat": {"type": "boolean"} - } -} \ No newline at end of file diff --git a/fixtures/v2.0/json/responses/voidResponse.json b/fixtures/v2.0/json/responses/voidResponse.json deleted file mode 100644 index a7edcadb32..0000000000 --- a/fixtures/v2.0/json/responses/voidResponse.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "description": "object created" -} \ No newline at end of file diff --git a/package.json b/package.json index a5b8cd1873..59851cb7dc 100644 --- a/package.json +++ b/package.json @@ -1,33 +1,35 @@ { - "name": "swagger-validator", - "version": "0.0.1", - "description": "validates a file", + "name": "oas-schemas", + "version": "2.0.0", + "description": "OpenAPI Specification JSON schemas", "author": { - "name": "Tony Tam", - "email": "fehguy@gmail.com", - "url": "http://swagger.io" + "name": "OpenAPI Initiative TSC", + "email": "tsc@openapis.org", + "url": "https://openapis.org/" }, - "license": "Apache", - "readmeFilename": "README.md", - "dependencies": { - "tv4": "~1.1.x", - "chai": "1.9.x" + "repository": { + "type": "git", + "url": "https://github.com/OAI/OpenAPI-Specification.git" }, + "license": "Apache-2.0", + "readmeFilename": "README.md", + "files": [ + "README.md", + "schemas/*" + ], + "dependencies": {}, "devDependencies": { - "glob": "^4.0.5", - "gulp": "~3.8.x", - "gulp-ext-replace": "^0.1.0", - "gulp-jsonlint": "0.0.3", - "gulp-util": "^3.0.0", - "gulp-yaml": "0.0.3", - "js-yaml": "^3.1.0", - "json2yaml": "^1.0.3", - "jsonschema": "^1.0.0", - "map-stream": "^0.1.0", - "mdv": "^1.0.3", - "mocha": "^1.21.3", - "q": "^1.0.1", - "request": "^2.39.0", - "z-schema": "^2.4.9" - } + "@hyperjump/json-schema": "^0.17.0", + "chai": "^4.3.1", + "mdv": "^1.0.7", + "mocha": "^8.3.0", + "yaml": "^1.8.3" + }, + "keywords": [ + "OpenAPI", + "OAS", + "Swagger", + "schema", + "API" + ] } diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md new file mode 100644 index 0000000000..da2a8b1eeb --- /dev/null +++ b/proposals/000_OAS-proposal-template.md @@ -0,0 +1,44 @@ +# Feature name + + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| +|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| +|Review Manager |TBD | +|Status |Proposal, Draft, Promoted, or Abandoned| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| +|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| +|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | + +## Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | + +## Introduction + +A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. + +## Motivation + +Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code. + +## Proposed solution + +Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? + +## Detailed design + +Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section. + +## Backwards compatibility + +Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed. + +## Alternatives considered + +Describe alternative approaches to addressing the same problem, and why you chose this approach instead. + diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md new file mode 100644 index 0000000000..9f176ea28e --- /dev/null +++ b/proposals/001_Alternative Schema Proposal.md @@ -0,0 +1,73 @@ +# Alternative Schema + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| +|Authors|[Chuck Heazel](https://github.com/{cmheazel})| +|Review Manager |TBD | +|Status |**Draft** | +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md) +|Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)| +|Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) | + +.Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | +|3/15/19 |C. Heazel|Initial Markup Draft | +|4/17/19 |C. Heazel|Re-structured based on Apple Swift| + +## Introduction + +This a proposal to add a new field called ``alternativeSchema`` to the OAS. + +## Motivation + +OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used. + +For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be. + +## Proposed solution + +This proposal makes the following changes to the OAS 3.0 specification: + +1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field. +1. Addition of the Alternative Schema Object. +1. Addition of Alternative Schema examples. +1. Addition of a preliminary discussion of the Alternative Schema registry. + +## Detailed design + +### Extend the Schema Object + +The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md) + +### Add the Alternative Schema Object + +The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md) + +### Provide Alternative Schema Examples +Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md) + +### Alternative Schema Registry + +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at
")+"
+ +Field Name | Type | Description +---|:---:|--- +nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. +
+ +## Detailed design + +According to the above specification, `nullable` only operates within a narrow scope, wherein its translation to JSON Schema is straightforward: + +* `nullable` is only meaningful if its value is `true`. + +* `nullable: true` is only meaningful in combination with a `type` assertion specified in the same Schema Object. `nullable` acts as a `type` modifier, allowing `null` in addition to the specified type. + +* `nullable: true` operates within a single Schema Object. It does not "override" or otherwise compete with supertype or subtype schemas defined with `allOf` or other applicators. It cannot be directly "inherited" through those applicators, and it cannot be applied to an inherited `type` constraint. + +This also solves the issues of alignment with JSON Schema: + +* Since `type` is a constraint, JSON Schema's constraint-based processing model is fully applicable. Interactions between `type` and other constraining assertions and applicators are unambiguous, with each constraint having independent veto power. + +* It is now clear that `nullable: false`, whether explicit or by default, _does not_ prohibit null values. Consistent with JSON Schema, an empty object allows all values, including `null`. + +### Questions Answered + +Following are answers to the questions posed above, assuming the proposed clarification is adopted: + +#### If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).) + +No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`. + +While the modified `type` now allows `null`, the `enum` does not. Consistent with JSON schema, a value conforms to the schema only if it is valid against _all_ constraints. Any constraint, in this case `enum`, can cause a value to fail validation, even if that value meets all of the other constraints. + +#### Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema? + +Yes, an untyped schema allows null values, in addition to all other types. `nullable: true` has no effect, because null values are already allowed. And `nullable: false` has no effect because it just leaves the `type` constraint unmodified. + +#### Can `allOf` be used to define a nullable subtype of a non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).) + +No. Subtypes can add constraints, but not relax them. + +#### Can `allOf` be used to define a non-nullable subtype of a nullable base schema? + +Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`. + +#### What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema? + +A nullable type should translate into a type array with two string elements: the name of the type specified in the Schema Object, and `"null"`. + +#### Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).) + +Yes. For example, a Schema Object with `"type" : "string", "nullable" : true` would translate to a JSON Schema with `"type" : ["string", "null"]`. That schema permits `"default" : null`, even with the [strict typing rule](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#properties) specified by OpenAPI 3.0: + +> default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. + +## Backwards compatibility + +Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations. + +With the clarification of `nullable: false`, we think the risk of actual breakage is miniscule, because the current ambiguity only affects untyped Schema Objects, which by their nature leave a lot of room for unexpected values. Any implementation that relies on schema validation to prevent null values should use explicitly typed schemas, and typed schemas unambiguously disallow `null` unless `nullable` is `true`. + +There might be a somewhat greater risk of breakage by specifying the effect of `nullable: true` as a `type` modifier. A more heavy-handed interpretation of `nullable: true`, [described here](https://github.com/OAI/OpenAPI-Specification/issues/1900#issuecomment-486772917), would make it equivalent to `anyOf [s, {type: "null"}]` where `s` is the schema as specified (excluding `nullable`). This would allow nulls even where they would be prohibited by other schema keywords, like `enum`. But this interpretation introduces far greater complexity than the narrowly scoped `type` modifier. We are not aware of any OpenAPI schema validator that actually attempts this, and there is nothing in the OpenAPI spec that says `nullable` can override constraining assertions. + +## Alternatives considered + +[Pull request #1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957) has some history of other approaches considered along the way. The first attempt assumed that `nullable: false` would prohibit null values, and attempted to work around this while maintaining backward compatibility. + +On closer inspection, the specification does not say anything about `null` values being disallowed. So we believe our interpretation is correct, and highly advantageous in its alignment with JSON Schema. diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md new file mode 100644 index 0000000000..de820558ba --- /dev/null +++ b/proposals/004_Overlays.md @@ -0,0 +1,232 @@ +# Overlays + +## Metadata + +|Tag |Value | +|---- | ---------------- | +|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| +|Authors|[Darrel Miller](https://github.com/darrelmiller)| +|Status |Proposal| +|Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)| + +## Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | +| 24th December 2019 | Darrel Miller | Initial draft | +| 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.| +| 29th July 2020 | Darrel Miller | Updated to be explicit about update operations | + +## Introduction + +In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date. + +#### Overlay Document + +An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. + + +#### Overlay Object + +This is the root object of the [OpenAPI Overlay document](#oasDocument). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +overlay | `string` | Version of the Overlay specification that this document conforms to. +info | [[Info Object](#overlayInfoObject)] | Identifying information about the overlay. +extends | `url` | URL to an OpenAPI document this overlay applies to. +updates | [[Update Object](#updateObject)] | A list of update objects to be applied to the target document. + +The list of update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update. + +The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. This is an optional property. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description. + +#### Info Object + +This object contains identifying information about the [OpenAPI Overlay document](#oasDocument). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human readable description of the purpose of the overlay. +version | `string` | A version identifer for indicating changes to an overlay document. + +#### Update Object + +This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +target | `string` | A JMESPath expression referencing the target objects in the target document. +add | [Any](#addObject) | An object to be added as a child of the object(s) referenced by the target. Property has no impact if `remove` property is `true`. +merge | [Any](#mergeObject) | An object with the properties and values to be merged with the object(s) referenced by the target. Property has no impact if `remove` property is `true`. +remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false. + +The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object. + +##### Structured Overlays Example + +When updating properties throughout the target document it may be more efficient to create a single `Update Object` that mirrors the structure of the target document. e.g. + +```yaml +overlay: 1.0.0 +info: + title: Structured Overlay + version: 1.0.0 +updates: +- target: "@" + merge: + info: + x-overlay-applied: structured-overlay + paths: + "/": + summary: "The root resource" + get: + summary: "Retrieve the root resource" + x-rate-limit: 100 + "/pets": + get: + summary: "Retrieve a list of pets" + x-rate-limit: 100 + components: + tags: +``` + +##### Targeted Overlays + +Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted. + +```yaml +overlay: 1.0.0 +info: + title: Targeted Overlays + version: 1.0.0 +updates: +- target: paths."/foo".get + merge: + description: This is the new description +- target: paths."/bar".get + merge: + description: This is the updated description +- target: paths."/bar" + merge: + post: + description: This is an updated description of a child object + x-safe: false +``` + +##### Wildcard Overlays Examples + +One significant advantage of using the JMESPath syntax that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards. + +```yaml +overlay: 1.0.0 +info: + title: Update many objects at once + version: 1.0.0 +updates: +- target: paths.*.get + merge: + x-safe: true +- target: paths.*.get.parameters[?name=='filter' && in=='query'] + merge: + schema: + $ref: "/components/schemas/filterSchema" +``` + +##### Array Modification Examples + +Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the `remove` property. Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed. + +```yaml +overlay: 1.0.0 +info: + title: Add an array element + version: 1.0.0 +updates: +- target: paths.*.get.parameters + add: + name: newParam + in: query +``` + +```yaml +overlay: 1.0.0 +info: + title: Remove a array element + version: 1.0.0 +updates: +- target: paths[*].get.parameters[? name == 'dummy'] + remove: true +``` + +##### Traits Examples + +By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied. + +```yaml +openapi: 3.1.0 +info: + title: Api with a paged collection + version: 1.0.0 +paths: + /items: + get: + x-oai-traits: ["paged"] + responses: + 200: + description: OK +``` + +With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied. + +```yaml +overlay: 1.0.0 +info: + title: Apply Traits + version: 1.0.0 +updates: +- target: $.paths[*].get[?contains(x-traits,'paged')] + merge: + parameters: + - name: top + in: query + - name: skip + in: query +``` + +This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself. + +## Proposal Summary + +### Benefits + +- This approach addresses the two distinct approaches of structured overlay vs targeted overlay which suits distinct but equally valid scenarios. +- Addresses the problem of modifying the parameters array and removes the need to replace the entire array when a small change is required. +- Allows sets of related overlays to be stored in a same file. +- Enables updating a set of objects based on a pattern. This might be an effective way of apply common behaviour across many operations in an API. + +### Challenges + +- Tooling will need a JMESPath implementation. +- Large overlays may be slow to process. +- Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes. + +## Alternatives considered + +JMESPath was chosen over JSONPath due to the fact that JMESPath has a [specification](http://jmespath.org/specification.html) and a set of test cases. This will help to ensure compatibility between implementations. + +## Backwards compatibility + +Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions. + +## Scenarios Considered + +- Multi-language support. An Overlay document for each language is used to target a specific OpenAPI description. The Overlay document will likely use a duplicate structure to the original OpenAPI description and replace all `description` properties. +- Applying API wide standards. An Overlay document contains update objects that describe standard headers, parameters, responses. These documents would use JMESPath queries to target the appropriate objects in the OpenAPI description. Tooling could be used to target the OpenAPI description rather than using extends. +- Add tool specific OpenAPI metadata. Overlay adds additional metadata such as SLA information, client codegen hints or middleware policies. Using Overlays to manage this data separately is valuable when there is a different audience for the data and/or there the information has different sensitivity levels. diff --git a/proposals/Alternative Schema/CONTRIBUTORS.md b/proposals/Alternative Schema/CONTRIBUTORS.md new file mode 100644 index 0000000000..227901b37a --- /dev/null +++ b/proposals/Alternative Schema/CONTRIBUTORS.md @@ -0,0 +1,2 @@ +* Chuck Heazel [@cmheazel](https://github.com/cmheazel) +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) \ No newline at end of file diff --git a/proposals/Alternative Schema/DEVELOPMENT.md b/proposals/Alternative Schema/DEVELOPMENT.md new file mode 100644 index 0000000000..65ff4b1684 --- /dev/null +++ b/proposals/Alternative Schema/DEVELOPMENT.md @@ -0,0 +1,38 @@ +## Development Guidelines + +TBD + +## Specification Driving factors + +TBD + +## Specification Change Criteria + +TBD + +## Specification Change Process + +TBD + +## Tracking Process + +* GitHub is the medium of record for all spec designs, use cases, and so on. + + +## Release Process + +TBD + +## Draft Features + + +## Transparency + + + +## Participation + + + +## Community Roles + diff --git a/proposals/Alternative Schema/alternative_schema_examples.md b/proposals/Alternative Schema/alternative_schema_examples.md new file mode 100644 index 0000000000..96f7189576 --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_examples.md @@ -0,0 +1,53 @@ +## Change: Add Alternative Schema Examples + +The following text is to be inserted after the Alternative Schema Object section. + +### Alternative Schema Examples + +Minimalist usage of alternative schema: + + schema: + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + +Combination of OAS schema and alternative: + + schema: + type: object + nullable: true + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + +Multiple different versions of alternative schema: + + schema: + anyOf: + - x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema-08.json + - x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema-07.json + +Combined alternative schemas: + + schema: + allOf: + - x-oas-draft-alternativeSchema: + type: xmlSchema + location: ./xmlSchema.xsd + - x-oas-draft-alternativeSchema: + type: schematron + location: ./schema.sch + +Mixed OAS schema and alternative schema: + + schema: + type: array + items: + x-oas-draft-alternativeSchema: + type: jsonSchema + location: ./real-jsonschema.json + diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.adoc new file mode 100644 index 0000000000..011f26b6b6 --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_object.adoc @@ -0,0 +1,16 @@ +## Change: Add the Alternative Schema Object + +The following text is to be inserted after the XML Object section + +### Alternative Schema Object + +This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed. + +==== Fixed Fields + +|Field Name | Type | Description | +|---|:---:|---| +|type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. | +|location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. | + +This object MAY be extended with Specification Extensions. diff --git a/proposals/Alternative Schema/implementations.md b/proposals/Alternative Schema/implementations.md new file mode 100644 index 0000000000..f1d61e48f2 --- /dev/null +++ b/proposals/Alternative Schema/implementations.md @@ -0,0 +1,46 @@ +# Implementations + +## Overview + +Below is a list of tooling that claims to implement the Alternative Schema proposal. While support for this feature matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the OpenAPI specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. + +These tools are not endorsed by the OAI + +## Implementations: + +#### Low-Level tooling + +| Title | Project Link | Language | Description +| ----------- | ----------- | ----------- | ----------- +|TBD |TBD |TBD |TBD | + +#### Editors + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### User Interfaces + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### Mock Servers +| Title | Project Link | Language | Description | +| -------------- | ------------ | -------- | ----------- | +|TBD |TBD |TBD |TBD | + +#### Server Implementations +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + +#### Code Generators + +| Title | Project Link | Language |Description | +|----------------|--------------|----------|---------------------| +|TBD |TBD |TBD |TBD | + + + diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md new file mode 100644 index 0000000000..df8c64c8ff --- /dev/null +++ b/proposals/Alternative Schema/schema_object.md @@ -0,0 +1,17 @@ +## Change: Extend the Schema Object to support Alternative Schemas + +The following content shall be used to replace the Fixed Fields table in the Schema Object section + +#### Fixed Fields + +|Field Name | Type | Description | +|---|:---:|---| +| nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.| +| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. | +| readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | +| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | +| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. +| example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.| +| deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.| +|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | diff --git a/proposals/Overlays/Changes.yml b/proposals/Overlays/Changes.yml new file mode 100644 index 0000000000..d2abf79e64 --- /dev/null +++ b/proposals/Overlays/Changes.yml @@ -0,0 +1,70 @@ +# Create update methods (add,replace,merge,delete)? Is merge necessary? +# Multiple additions or updates to the same target is more efficient with merge + +# Different than JSON Patch because is works in JSON and YAML +# Has info object and spec version +# values + +overlay: 1.0.0 +info: + title: An example of an overlay that captures changes to an API + version: 1.0.0 +updates: +# Add a property to a schema +- target: components.schemas."todo".properties + merge: + createdBy: + type: string +# Add constraints to a schema +- target: components.schemas."todo" + merge: + additionalProperties: false +- target: components.schemas."todo" + merge: + type: ["object","null"] +#Change a schema +- target: components.schemas."todo" + replace: + type: integer +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] + properties: + someprop: + type: string +# Add an operation +- target: paths."/foo" + add: + delete: + description: delete a foo + responses: + 200: + description: ok +# Add a path +- target: paths + add: + "/items": + get: + responses: + 200: + description: ok +# Add an optional query parameter +- target: paths."/bar".parameters + add: + name: skip + in: query + type: string +# Mark an operation as deprecated + +# Change the value of a JSON schema constraint +# Update the version of the API +# Change the license of an API +# Add support for a new request media type +# Add support for a new response media type diff --git a/proposals/Overlays/MergePatch.yml b/proposals/Overlays/MergePatch.yml new file mode 100644 index 0000000000..3bd4d0a1cb --- /dev/null +++ b/proposals/Overlays/MergePatch.yml @@ -0,0 +1,10 @@ +overlay: 1.0.0 +info: + title: An example of an overlay that performs a Merge Patch + version: 1.0.0 +updates: +- target: "@" + merge: + openapi: 3.0.3 + paths: {} + diff --git a/schemas/v2.0/README.md b/schemas/v2.0/README.md index becb22d06e..47b0c8e817 100644 --- a/schemas/v2.0/README.md +++ b/schemas/v2.0/README.md @@ -1,6 +1,6 @@ -# Swagger Specification JSON Schemas +# OpenAPI Specification v2.0 JSON Schema -This is only JSON Schema file for Swagger version 2.0. Download and Install it via NPM or Bower. +This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM. ## Install via NPM @@ -8,17 +8,6 @@ This is only JSON Schema file for Swagger version 2.0. Download and Install it v npm install --save swagger-schema-official ``` -#### Install 1.2 version via NPM - -```shell -npm install --save swagger-schema-official@1.2.0 -``` -## Install via Bower - - ```shell - bower install --save swagger-schema - ``` - ## License Apache-2.0 diff --git a/schemas/v2.0/bower.json b/schemas/v2.0/bower.json deleted file mode 100644 index 1049d27104..0000000000 --- a/schemas/v2.0/bower.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "swagger-schema", - "version": "2.0.0-96305d9", - "homepage": "https://github.com/swagger-api/swagger-schema", - "authors": [ - "''" - ], - "main": "./schema.json", - "description": "Swagger JSON Schema", - "keywords": [ - "swagger", - "schema", - "api" - ], - "license": "Apache-2.0" -} diff --git a/schemas/v2.0/package.json b/schemas/v2.0/package.json deleted file mode 100644 index 2c9d724182..0000000000 --- a/schemas/v2.0/package.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "name": "swagger-schema-official", - "version": "2.0.0-bab6bed", - "description": "Swagger JSON Schema ", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "keywords": [ - "swagger", - "schema", - "api" - ], - "author": "", - "main": "./schema.json", - "license": "Apache-2.0" -} diff --git a/schemas/v3.0/README.md b/schemas/v3.0/README.md new file mode 100644 index 0000000000..84956279da --- /dev/null +++ b/schemas/v3.0/README.md @@ -0,0 +1,16 @@ +OpenAPI 3.0.X JSON Schema +--- + +Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.0.X. + +As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. + +The iteration version of the JSON Schema can be found in the `id` field. For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. + +To submit improvements to the schema, modify the schema.yaml file only. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Convert the schema.yaml to schema.json +- Publish the new version diff --git a/schemas/v3.0/schema.json b/schemas/v3.0/schema.json new file mode 100644 index 0000000000..71808402f6 --- /dev/null +++ b/schemas/v3.0/schema.json @@ -0,0 +1,1654 @@ +{ + "id": "https://spec.openapis.org/oas/3.0/schema/2019-04-02", + "$schema": "http://json-schema.org/draft-04/schema#", + "description": "Validation schema for OpenAPI Specification 3.0.X.", + "type": "object", + "required": [ + "openapi", + "info", + "paths" + ], + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.0\\.\\d(-.+)?$" + }, + "info": { + "$ref": "#/definitions/Info" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/SecurityRequirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/Tag" + }, + "uniqueItems": true + }, + "paths": { + "$ref": "#/definitions/Paths" + }, + "components": { + "$ref": "#/definitions/Components" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "definitions": { + "Reference": { + "type": "object", + "required": [ + "$ref" + ], + "patternProperties": { + "^\\$ref$": { + "type": "string", + "format": "uri-reference" + } + } + }, + "Info": { + "type": "object", + "required": [ + "title", + "version" + ], + "properties": { + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string", + "format": "uri-reference" + }, + "contact": { + "$ref": "#/definitions/Contact" + }, + "license": { + "$ref": "#/definitions/License" + }, + "version": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + }, + "email": { + "type": "string", + "format": "email" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "License": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Server": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ServerVariable" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ServerVariable": { + "type": "object", + "required": [ + "default" + ], + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + } + }, + "default": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "responses": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Response" + } + ] + } + } + }, + "parameters": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Parameter" + } + ] + } + } + }, + "examples": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Example" + } + ] + } + } + }, + "requestBodies": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/RequestBody" + } + ] + } + } + }, + "headers": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Header" + } + ] + } + } + }, + "securitySchemes": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/SecurityScheme" + } + ] + } + } + }, + "links": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Link" + } + ] + } + } + }, + "callbacks": { + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "oneOf": [ + { + "$ref": "#/definitions/Reference" + }, + { + "$ref": "#/definitions/Callback" + } + ] + } + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Schema": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "multipleOf": { + "type": "number", + "minimum": 0, + "exclusiveMinimum": true + }, + "maximum": { + "type": "number" + }, + "exclusiveMaximum": { + "type": "boolean", + "default": false + }, + "minimum": { + "type": "number" + }, + "exclusiveMinimum": { + "type": "boolean", + "default": false + }, + "maxLength": { + "type": "integer", + "minimum": 0 + }, + "minLength": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "pattern": { + "type": "string", + "format": "regex" + }, + "maxItems": { + "type": "integer", + "minimum": 0 + }, + "minItems": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "uniqueItems": { + "type": "boolean", + "default": false + }, + "maxProperties": { + "type": "integer", + "minimum": 0 + }, + "minProperties": { + "type": "integer", + "minimum": 0, + "default": 0 + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "uniqueItems": true + }, + "enum": { + "type": "array", + "items": { + }, + "minItems": 1, + "uniqueItems": false + }, + "type": { + "type": "string", + "enum": [ + "array", + "boolean", + "integer", + "number", + "object", + "string" + ] + }, + "not": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "allOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "oneOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "anyOf": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "properties": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + }, + { + "type": "boolean" + } + ], + "default": true + }, + "description": { + "type": "string" + }, + "format": { + "type": "string" + }, + "default": { + }, + "nullable": { + "type": "boolean", + "default": false + }, + "discriminator": { + "$ref": "#/definitions/Discriminator" + }, + "readOnly": { + "type": "boolean", + "default": false + }, + "writeOnly": { + "type": "boolean", + "default": false + }, + "example": { + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "xml": { + "$ref": "#/definitions/XML" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Discriminator": { + "type": "object", + "required": [ + "propertyName" + ], + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "XML": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean", + "default": false + }, + "wrapped": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Response": { + "type": "object", + "required": [ + "description" + ], + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Header" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Link" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "MediaType": { + "type": "object", + "properties": { + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Encoding" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + } + ] + }, + "Example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": { + }, + "externalValue": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string", + "enum": [ + "simple" + ], + "default": "simple" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + }, + { + "$ref": "#/definitions/SchemaXORContent" + } + ] + }, + "Paths": { + "type": "object", + "patternProperties": { + "^\\/": { + "$ref": "#/definitions/PathItem" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "PathItem": { + "type": "object", + "properties": { + "$ref": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Parameter" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "uniqueItems": true + } + }, + "patternProperties": { + "^(get|put|post|delete|options|head|patch|trace)$": { + "$ref": "#/definitions/Operation" + }, + "^x-": { + } + }, + "additionalProperties": false + }, + "Operation": { + "type": "object", + "required": [ + "responses" + ], + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "oneOf": [ + { + "$ref": "#/definitions/Parameter" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "uniqueItems": true + }, + "requestBody": { + "oneOf": [ + { + "$ref": "#/definitions/RequestBody" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "responses": { + "$ref": "#/definitions/Responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Callback" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "security": { + "type": "array", + "items": { + "$ref": "#/definitions/SecurityRequirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/definitions/Server" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Responses": { + "type": "object", + "properties": { + "default": { + "oneOf": [ + { + "$ref": "#/definitions/Response" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + }, + "patternProperties": { + "^[1-5](?:\\d{2}|XX)$": { + "oneOf": [ + { + "$ref": "#/definitions/Response" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "^x-": { + } + }, + "minProperties": 1, + "additionalProperties": false + }, + "SecurityRequirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "Tag": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/definitions/ExternalDocumentation" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExternalDocumentation": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "description": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri-reference" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ExampleXORExamples": { + "description": "Example and examples are mutually exclusive", + "not": { + "required": [ + "example", + "examples" + ] + } + }, + "SchemaXORContent": { + "description": "Schema and content are mutually exclusive, at least one is required", + "not": { + "required": [ + "schema", + "content" + ] + }, + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ], + "description": "Some properties are not allowed if content is present", + "allOf": [ + { + "not": { + "required": [ + "style" + ] + } + }, + { + "not": { + "required": [ + "explode" + ] + } + }, + { + "not": { + "required": [ + "allowReserved" + ] + } + }, + { + "not": { + "required": [ + "example" + ] + } + }, + { + "not": { + "required": [ + "examples" + ] + } + } + ] + } + ] + }, + "Parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "type": "string" + }, + "description": { + "type": "string" + }, + "required": { + "type": "boolean", + "default": false + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "allowEmptyValue": { + "type": "boolean", + "default": false + }, + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + }, + "schema": { + "oneOf": [ + { + "$ref": "#/definitions/Schema" + }, + { + "$ref": "#/definitions/Reference" + } + ] + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + }, + "minProperties": 1, + "maxProperties": 1 + }, + "example": { + }, + "examples": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/Example" + }, + { + "$ref": "#/definitions/Reference" + } + ] + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "required": [ + "name", + "in" + ], + "allOf": [ + { + "$ref": "#/definitions/ExampleXORExamples" + }, + { + "$ref": "#/definitions/SchemaXORContent" + }, + { + "$ref": "#/definitions/ParameterLocation" + } + ] + }, + "ParameterLocation": { + "description": "Parameter location", + "oneOf": [ + { + "description": "Parameter in path", + "required": [ + "required" + ], + "properties": { + "in": { + "enum": [ + "path" + ] + }, + "style": { + "enum": [ + "matrix", + "label", + "simple" + ], + "default": "simple" + }, + "required": { + "enum": [ + true + ] + } + } + }, + { + "description": "Parameter in query", + "properties": { + "in": { + "enum": [ + "query" + ] + }, + "style": { + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ], + "default": "form" + } + } + }, + { + "description": "Parameter in header", + "properties": { + "in": { + "enum": [ + "header" + ] + }, + "style": { + "enum": [ + "simple" + ], + "default": "simple" + } + } + }, + { + "description": "Parameter in cookie", + "properties": { + "in": { + "enum": [ + "cookie" + ] + }, + "style": { + "enum": [ + "form" + ], + "default": "form" + } + } + } + ] + }, + "RequestBody": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "description": { + "type": "string" + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/MediaType" + } + }, + "required": { + "type": "boolean", + "default": false + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "SecurityScheme": { + "oneOf": [ + { + "$ref": "#/definitions/APIKeySecurityScheme" + }, + { + "$ref": "#/definitions/HTTPSecurityScheme" + }, + { + "$ref": "#/definitions/OAuth2SecurityScheme" + }, + { + "$ref": "#/definitions/OpenIdConnectSecurityScheme" + } + ] + }, + "APIKeySecurityScheme": { + "type": "object", + "required": [ + "type", + "name", + "in" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "apiKey" + ] + }, + "name": { + "type": "string" + }, + "in": { + "type": "string", + "enum": [ + "header", + "query", + "cookie" + ] + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "HTTPSecurityScheme": { + "type": "object", + "required": [ + "scheme", + "type" + ], + "properties": { + "scheme": { + "type": "string" + }, + "bearerFormat": { + "type": "string" + }, + "description": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "http" + ] + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "oneOf": [ + { + "description": "Bearer", + "properties": { + "scheme": { + "enum": [ + "bearer" + ] + } + } + }, + { + "description": "Non Bearer", + "not": { + "required": [ + "bearerFormat" + ] + }, + "properties": { + "scheme": { + "not": { + "enum": [ + "bearer" + ] + } + } + } + } + ] + }, + "OAuth2SecurityScheme": { + "type": "object", + "required": [ + "type", + "flows" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "oauth2" + ] + }, + "flows": { + "$ref": "#/definitions/OAuthFlows" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OpenIdConnectSecurityScheme": { + "type": "object", + "required": [ + "type", + "openIdConnectUrl" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "openIdConnect" + ] + }, + "openIdConnectUrl": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "OAuthFlows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/definitions/ImplicitOAuthFlow" + }, + "password": { + "$ref": "#/definitions/PasswordOAuthFlow" + }, + "clientCredentials": { + "$ref": "#/definitions/ClientCredentialsFlow" + }, + "authorizationCode": { + "$ref": "#/definitions/AuthorizationCodeOAuthFlow" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ImplicitOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "scopes" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "PasswordOAuthFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "ClientCredentialsFlow": { + "type": "object", + "required": [ + "tokenUrl" + ], + "properties": { + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "AuthorizationCodeOAuthFlow": { + "type": "object", + "required": [ + "authorizationUrl", + "tokenUrl" + ], + "properties": { + "authorizationUrl": { + "type": "string", + "format": "uri-reference" + }, + "tokenUrl": { + "type": "string", + "format": "uri-reference" + }, + "refreshUrl": { + "type": "string", + "format": "uri-reference" + }, + "scopes": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false + }, + "Link": { + "type": "object", + "properties": { + "operationId": { + "type": "string" + }, + "operationRef": { + "type": "string", + "format": "uri-reference" + }, + "parameters": { + "type": "object", + "additionalProperties": { + } + }, + "requestBody": { + }, + "description": { + "type": "string" + }, + "server": { + "$ref": "#/definitions/Server" + } + }, + "patternProperties": { + "^x-": { + } + }, + "additionalProperties": false, + "not": { + "description": "Operation Id and Operation Ref are mutually exclusive", + "required": [ + "operationId", + "operationRef" + ] + } + }, + "Callback": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/PathItem" + }, + "patternProperties": { + "^x-": { + } + } + }, + "Encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/Header" + } + }, + "style": { + "type": "string", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "type": "boolean", + "default": false + } + }, + "additionalProperties": false + } + } +} \ No newline at end of file diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml new file mode 100644 index 0000000000..13e47ff08d --- /dev/null +++ b/schemas/v3.0/schema.yaml @@ -0,0 +1,1003 @@ +id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 +$schema: http://json-schema.org/draft-04/schema# +description: Validation schema for OpenAPI Specification 3.0.X. +type: object +required: + - openapi + - info + - paths +properties: + openapi: + type: string + pattern: ^3\.0\.\d(-.+)?$ + info: + $ref: '#/definitions/Info' + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + servers: + type: array + items: + $ref: '#/definitions/Server' + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + tags: + type: array + items: + $ref: '#/definitions/Tag' + uniqueItems: true + paths: + $ref: '#/definitions/Paths' + components: + $ref: '#/definitions/Components' +patternProperties: + '^x-': {} +additionalProperties: false +definitions: + Reference: + type: object + required: + - $ref + patternProperties: + '^\$ref$': + type: string + format: uri-reference + Info: + type: object + required: + - title + - version + properties: + title: + type: string + description: + type: string + termsOfService: + type: string + format: uri-reference + contact: + $ref: '#/definitions/Contact' + license: + $ref: '#/definitions/License' + version: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + + Contact: + type: object + properties: + name: + type: string + url: + type: string + format: uri-reference + email: + type: string + format: email + patternProperties: + '^x-': {} + additionalProperties: false + + License: + type: object + required: + - name + properties: + name: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Server: + type: object + required: + - url + properties: + url: + type: string + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/definitions/ServerVariable' + patternProperties: + '^x-': {} + additionalProperties: false + + ServerVariable: + type: object + required: + - default + properties: + enum: + type: array + items: + type: string + default: + type: string + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Components: + type: object + properties: + schemas: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + responses: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Response' + parameters: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Parameter' + examples: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Example' + requestBodies: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/RequestBody' + headers: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Header' + securitySchemes: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/SecurityScheme' + links: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Link' + callbacks: + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + oneOf: + - $ref: '#/definitions/Reference' + - $ref: '#/definitions/Callback' + patternProperties: + '^x-': {} + additionalProperties: false + + Schema: + type: object + properties: + title: + type: string + multipleOf: + type: number + minimum: 0 + exclusiveMinimum: true + maximum: + type: number + exclusiveMaximum: + type: boolean + default: false + minimum: + type: number + exclusiveMinimum: + type: boolean + default: false + maxLength: + type: integer + minimum: 0 + minLength: + type: integer + minimum: 0 + default: 0 + pattern: + type: string + format: regex + maxItems: + type: integer + minimum: 0 + minItems: + type: integer + minimum: 0 + default: 0 + uniqueItems: + type: boolean + default: false + maxProperties: + type: integer + minimum: 0 + minProperties: + type: integer + minimum: 0 + default: 0 + required: + type: array + items: + type: string + minItems: 1 + uniqueItems: true + enum: + type: array + items: {} + minItems: 1 + uniqueItems: false + type: + type: string + enum: + - array + - boolean + - integer + - number + - object + - string + not: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + allOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + oneOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + anyOf: + type: array + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + items: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + properties: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + additionalProperties: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + - type: boolean + default: true + description: + type: string + format: + type: string + default: {} + nullable: + type: boolean + default: false + discriminator: + $ref: '#/definitions/Discriminator' + readOnly: + type: boolean + default: false + writeOnly: + type: boolean + default: false + example: {} + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + deprecated: + type: boolean + default: false + xml: + $ref: '#/definitions/XML' + patternProperties: + '^x-': {} + additionalProperties: false + + Discriminator: + type: object + required: + - propertyName + properties: + propertyName: + type: string + mapping: + type: object + additionalProperties: + type: string + + XML: + type: object + properties: + name: + type: string + namespace: + type: string + format: uri + prefix: + type: string + attribute: + type: boolean + default: false + wrapped: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + Response: + type: object + required: + - description + properties: + description: + type: string + headers: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + links: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Link' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + + MediaType: + type: object + properties: + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + encoding: + type: object + additionalProperties: + $ref: '#/definitions/Encoding' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + + Example: + type: object + properties: + summary: + type: string + description: + type: string + value: {} + externalValue: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + Header: + type: object + properties: + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + enum: + - simple + default: simple + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + + Paths: + type: object + patternProperties: + '^\/': + $ref: '#/definitions/PathItem' + '^x-': {} + additionalProperties: false + + PathItem: + type: object + properties: + $ref: + type: string + summary: + type: string + description: + type: string + servers: + type: array + items: + $ref: '#/definitions/Server' + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + patternProperties: + '^(get|put|post|delete|options|head|patch|trace)$': + $ref: '#/definitions/Operation' + '^x-': {} + additionalProperties: false + + Operation: + type: object + required: + - responses + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + operationId: + type: string + parameters: + type: array + items: + oneOf: + - $ref: '#/definitions/Parameter' + - $ref: '#/definitions/Reference' + uniqueItems: true + requestBody: + oneOf: + - $ref: '#/definitions/RequestBody' + - $ref: '#/definitions/Reference' + responses: + $ref: '#/definitions/Responses' + callbacks: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Callback' + - $ref: '#/definitions/Reference' + deprecated: + type: boolean + default: false + security: + type: array + items: + $ref: '#/definitions/SecurityRequirement' + servers: + type: array + items: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + + Responses: + type: object + properties: + default: + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + patternProperties: + '^[1-5](?:\d{2}|XX)$': + oneOf: + - $ref: '#/definitions/Response' + - $ref: '#/definitions/Reference' + '^x-': {} + minProperties: 1 + additionalProperties: false + + + SecurityRequirement: + type: object + additionalProperties: + type: array + items: + type: string + + Tag: + type: object + required: + - name + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/definitions/ExternalDocumentation' + patternProperties: + '^x-': {} + additionalProperties: false + + ExternalDocumentation: + type: object + required: + - url + properties: + description: + type: string + url: + type: string + format: uri-reference + patternProperties: + '^x-': {} + additionalProperties: false + + ExampleXORExamples: + description: Example and examples are mutually exclusive + not: + required: [example, examples] + + SchemaXORContent: + description: Schema and content are mutually exclusive, at least one is required + not: + required: [schema, content] + oneOf: + - required: [schema] + - required: [content] + description: Some properties are not allowed if content is present + allOf: + - not: + required: [style] + - not: + required: [explode] + - not: + required: [allowReserved] + - not: + required: [example] + - not: + required: [examples] + + Parameter: + type: object + properties: + name: + type: string + in: + type: string + description: + type: string + required: + type: boolean + default: false + deprecated: + type: boolean + default: false + allowEmptyValue: + type: boolean + default: false + style: + type: string + explode: + type: boolean + allowReserved: + type: boolean + default: false + schema: + oneOf: + - $ref: '#/definitions/Schema' + - $ref: '#/definitions/Reference' + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + minProperties: 1 + maxProperties: 1 + example: {} + examples: + type: object + additionalProperties: + oneOf: + - $ref: '#/definitions/Example' + - $ref: '#/definitions/Reference' + patternProperties: + '^x-': {} + additionalProperties: false + required: + - name + - in + allOf: + - $ref: '#/definitions/ExampleXORExamples' + - $ref: '#/definitions/SchemaXORContent' + - $ref: '#/definitions/ParameterLocation' + + ParameterLocation: + description: Parameter location + oneOf: + - description: Parameter in path + required: + - required + properties: + in: + enum: [path] + style: + enum: [matrix, label, simple] + default: simple + required: + enum: [true] + + - description: Parameter in query + properties: + in: + enum: [query] + style: + enum: [form, spaceDelimited, pipeDelimited, deepObject] + default: form + + - description: Parameter in header + properties: + in: + enum: [header] + style: + enum: [simple] + default: simple + + - description: Parameter in cookie + properties: + in: + enum: [cookie] + style: + enum: [form] + default: form + + RequestBody: + type: object + required: + - content + properties: + description: + type: string + content: + type: object + additionalProperties: + $ref: '#/definitions/MediaType' + required: + type: boolean + default: false + patternProperties: + '^x-': {} + additionalProperties: false + + SecurityScheme: + oneOf: + - $ref: '#/definitions/APIKeySecurityScheme' + - $ref: '#/definitions/HTTPSecurityScheme' + - $ref: '#/definitions/OAuth2SecurityScheme' + - $ref: '#/definitions/OpenIdConnectSecurityScheme' + + APIKeySecurityScheme: + type: object + required: + - type + - name + - in + properties: + type: + type: string + enum: + - apiKey + name: + type: string + in: + type: string + enum: + - header + - query + - cookie + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + HTTPSecurityScheme: + type: object + required: + - scheme + - type + properties: + scheme: + type: string + bearerFormat: + type: string + description: + type: string + type: + type: string + enum: + - http + patternProperties: + '^x-': {} + additionalProperties: false + oneOf: + - description: Bearer + properties: + scheme: + enum: [bearer] + + - description: Non Bearer + not: + required: [bearerFormat] + properties: + scheme: + not: + enum: [bearer] + + OAuth2SecurityScheme: + type: object + required: + - type + - flows + properties: + type: + type: string + enum: + - oauth2 + flows: + $ref: '#/definitions/OAuthFlows' + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OpenIdConnectSecurityScheme: + type: object + required: + - type + - openIdConnectUrl + properties: + type: + type: string + enum: + - openIdConnect + openIdConnectUrl: + type: string + format: uri-reference + description: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + OAuthFlows: + type: object + properties: + implicit: + $ref: '#/definitions/ImplicitOAuthFlow' + password: + $ref: '#/definitions/PasswordOAuthFlow' + clientCredentials: + $ref: '#/definitions/ClientCredentialsFlow' + authorizationCode: + $ref: '#/definitions/AuthorizationCodeOAuthFlow' + patternProperties: + '^x-': {} + additionalProperties: false + + ImplicitOAuthFlow: + type: object + required: + - authorizationUrl + - scopes + properties: + authorizationUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + PasswordOAuthFlow: + type: object + required: + - tokenUrl + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + ClientCredentialsFlow: + type: object + required: + - tokenUrl + properties: + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + AuthorizationCodeOAuthFlow: + type: object + required: + - authorizationUrl + - tokenUrl + properties: + authorizationUrl: + type: string + format: uri-reference + tokenUrl: + type: string + format: uri-reference + refreshUrl: + type: string + format: uri-reference + scopes: + type: object + additionalProperties: + type: string + patternProperties: + '^x-': {} + additionalProperties: false + + Link: + type: object + properties: + operationId: + type: string + operationRef: + type: string + format: uri-reference + parameters: + type: object + additionalProperties: {} + requestBody: {} + description: + type: string + server: + $ref: '#/definitions/Server' + patternProperties: + '^x-': {} + additionalProperties: false + not: + description: Operation Id and Operation Ref are mutually exclusive + required: [operationId, operationRef] + + Callback: + type: object + additionalProperties: + $ref: '#/definitions/PathItem' + patternProperties: + '^x-': {} + + Encoding: + type: object + properties: + contentType: + type: string + headers: + type: object + additionalProperties: + $ref: '#/definitions/Header' + style: + type: string + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + type: boolean + default: false + additionalProperties: false diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md new file mode 100644 index 0000000000..01da62b56d --- /dev/null +++ b/schemas/v3.1/README.md @@ -0,0 +1,41 @@ +# OpenAPI 3.1.X JSON Schema + +Here you can find the JSON Schema for validating OpenAPI definitions of versions +3.1.X. + +As a reminder, the JSON Schema is not the source of truth for the Specification. +In cases of conflicts between the Specification itself and the JSON Schema, the +Specification wins. Also, some Specification constraints cannot be represented +with the JSON Schema so it's highly recommended to employ other methods to +ensure compliance. + +The iteration version of the JSON Schema can be found in the `$id` field. For +example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` +means this iteration was created on March 2nd, 2021. + +The `schema.yaml` schema doesn't validate the JSON Schemas in your OpenAPI +document because 3.1 allows you to use any JSON Schema dialect you choose. We +have also included `schema-base.yaml` that extends the main schema to validate +that all schemas use the default OAS base vocabulary. + +## Contributing +To submit improvements to the schema, modify the schema.yaml file only. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Convert the schema.yaml to schema.json +- Publish the new version + +## Tests +The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. + +```bash +npx mocha --recursive tests +``` + +You can also validate a document individually. + +```bash +scripts/validate.js path/to/document/to/validate.yaml +``` diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json new file mode 100644 index 0000000000..d54b0d4d7c --- /dev/null +++ b/schemas/v3.1/dialect/base.schema.json @@ -0,0 +1,21 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/dialect/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/core": true, + "https://json-schema.org/draft/2020-12/vocab/applicator": true, + "https://json-schema.org/draft/2020-12/vocab/unevaluated": true, + "https://json-schema.org/draft/2020-12/vocab/validation": true, + "https://json-schema.org/draft/2020-12/vocab/meta-data": true, + "https://json-schema.org/draft/2020-12/vocab/format-annotation": true, + "https://json-schema.org/draft/2020-12/vocab/content": true, + "https://spec.openapis.org/oas/3.1/vocab/base": false + }, + "$dynamicAnchor": "meta", + + "title": "OpenAPI 3.1 Schema Object Dialect", + "allOf": [ + { "$ref": "https://json-schema.org/draft/2020-12/schema" }, + { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } + ] +} diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json new file mode 100644 index 0000000000..f3ee03fb96 --- /dev/null +++ b/schemas/v3.1/meta/base.schema.json @@ -0,0 +1,79 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/meta/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://spec.openapis.org/oas/3.1/vocab/base": true + }, + "$dynamicAnchor": "meta", + "title": "OAS Base vocabulary", + + "type": ["object", "boolean"], + "properties": { + "example": true, + "discriminator": { "$ref": "#/$defs/discriminator" }, + "externalDocs": { "$ref": "#/$defs/external-docs" }, + "xml": { "$ref": "#/$defs/xml" } + }, + "$defs": { + "extensible": { + "patternProperties": { + "^x-": true + } + }, + "discriminator": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": ["propertyName"], + "unevaluatedProperties": false + }, + "external-docs": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "required": ["url"], + "unevaluatedProperties": false + }, + "xml": { + "$ref": "#/$defs/extensible", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean" + }, + "wrapped": { + "type": "boolean" + } + }, + "unevaluatedProperties": false + } + } +} diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json new file mode 100644 index 0000000000..658e943cc5 --- /dev/null +++ b/schemas/v3.1/schema-base.json @@ -0,0 +1,24 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-04-15", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", + "properties": { + "jsonSchemaDialect": { + "$ref": "#/$defs/dialect" + } + }, + "$defs": { + "dialect": { + "const": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "schema": { + "$dynamicAnchor": "meta", + "$ref\"": "https://spec.openapis.org/oas/3.1/dialect/base", + "properties": { + "$schema": { + "$ref": "#/$defs/dialect" + } + } + } + } +} diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml new file mode 100644 index 0000000000..515ed08989 --- /dev/null +++ b/schemas/v3.1/schema-base.yaml @@ -0,0 +1,17 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-04-15' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' +properties: + jsonSchemaDialect: + $ref: '#/$defs/dialect' + +$defs: + dialect: + const: 'https://spec.openapis.org/oas/3.1/dialect/base' + schema: + $dynamicAnchor: meta + $ref": 'https://spec.openapis.org/oas/3.1/dialect/base' + properties: + $schema: + $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json new file mode 100644 index 0000000000..a798834247 --- /dev/null +++ b/schemas/v3.1/schema.json @@ -0,0 +1,1343 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "openapi": { + "type": "string", + "pattern": "^3\\.1\\.\\d+(-.+)?$" + }, + "info": { + "$ref": "#/$defs/info" + }, + "jsonSchemaDialect": { + "$ref": "#/$defs/uri", + "default": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "paths": { + "$ref": "#/$defs/paths" + }, + "webhooks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "components": { + "$ref": "#/$defs/components" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/$defs/tag" + } + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "openapi", + "info" + ], + "anyOf": [ + { + "required": [ + "paths" + ] + }, + { + "required": [ + "components" + ] + }, + { + "required": [ + "webhooks" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "info": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string" + }, + "contact": { + "$ref": "#/$defs/contact" + }, + "license": { + "$ref": "#/$defs/license" + }, + "version": { + "type": "string" + } + }, + "required": [ + "title", + "version" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "license": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "identifier": { + "type": "string" + }, + "url": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "name" + ], + "oneOf": [ + { + "required": [ + "identifier" + ] + }, + { + "required": [ + "url" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server": { + "type": "object", + "properties": { + "url": { + "$ref": "#/$defs/uri" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/server-variable" + } + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server-variable": { + "type": "object", + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "default": { + "type": "string" + }, + "descriptions": { + "type": "string" + } + }, + "required": [ + "default" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "additionalProperties": { + "$dynamicRef": "#meta" + } + }, + "responses": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/response-or-reference" + } + }, + "parameters": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + }, + "requestBodies": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/request-body-or-reference" + } + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "securitySchemes": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/security-scheme-or-reference" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "pathItems": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + } + }, + "patternProperties": { + "^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$": { + "$comment": "Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected", + "propertyNames": { + "pattern": "^[a-zA-Z0-9._-]+$" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "paths": { + "type": "object", + "patternProperties": { + "^/": { + "$ref": "#/$defs/path-item" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + } + } + }, + "patternProperties": { + "^(get|put|post|delete|options|head|patch|trace)$": { + "$ref": "#/$defs/operation" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/path-item" + } + }, + "operation": { + "type": "object", + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "requestBody": { + "$ref": "#/$defs/request-body-or-reference" + }, + "responses": { + "$ref": "#/$defs/responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "external-documentation": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "url": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "path", + "cookie" + ] + }, + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "$ref": "#/$defs/content" + } + }, + "required": [ + "in" + ], + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form" + } + ], + "$defs": { + "styles-for-path": { + "if": { + "properties": { + "in": { + "const": "path" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "matrix", + "label", + "simple" + ] + }, + "required": { + "const": true + } + }, + "required": [ + "required" + ] + } + }, + "styles-for-header": { + "if": { + "properties": { + "in": { + "const": "header" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + } + } + } + }, + "styles-for-query": { + "if": { + "properties": { + "in": { + "const": "query" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + } + } + } + }, + "styles-for-cookie": { + "if": { + "properties": { + "in": { + "const": "cookie" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form" + ] + } + } + } + }, + "styles-for-form": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/parameter" + } + }, + "request-body": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "content": { + "$ref": "#/$defs/content" + }, + "required": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "content" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "request-body-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/request-body" + } + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + }, + "propertyNames": { + "format": "media-range" + } + }, + "media-type": { + "type": "object", + "properties": { + "schema": { + "$dynamicRef": "#meta" + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/encoding" + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/examples" + } + ], + "unevaluatedProperties": false + }, + "encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string", + "format": "media-range" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/encoding/$defs/explode-default" + } + ], + "unevaluatedProperties": false, + "$defs": { + "explode-default": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + }, + "responses": { + "type": "object", + "properties": { + "default": { + "$ref": "#/$defs/response-or-reference" + } + }, + "patternProperties": { + "^[1-5][0-9X]{2}$": { + "$ref": "#/$defs/response-or-reference" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "content": { + "$ref": "#/$defs/content" + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + } + }, + "required": [ + "description" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/response" + } + }, + "callbacks": { + "type": "object", + "$ref": "#/$defs/specification-extensions", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "callbacks-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/callbacks" + } + }, + "example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": true, + "externalValue": { + "$ref": "#/$defs/uri" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "example-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/example" + } + }, + "link": { + "type": "object", + "properties": { + "operationRef": { + "$ref": "#/$defs/uri" + }, + "operationId": true, + "parameters": { + "$ref": "#/$defs/map-of-strings" + }, + "requestBody": true, + "description": { + "type": "string" + }, + "body": { + "$ref": "#/$defs/server" + } + }, + "oneOf": [ + { + "required": [ + "operationRef" + ] + }, + { + "required": [ + "operationId" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "link-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/link" + } + }, + "header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + }, + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + }, + "explode": { + "default": false, + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + } + }, + "$ref": "#/$defs/examples" + }, + "content": { + "properties": { + "content": { + "$ref": "#/$defs/content" + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "header-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/header" + } + }, + "tag": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "name" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "reference": { + "type": "object", + "properties": { + "$ref": { + "$ref": "#/$defs/uri" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "unevaluatedProperties": false + }, + "schema": { + "$dynamicAnchor": "meta", + "type": [ + "object", + "boolean" + ] + }, + "security-scheme": { + "type": "object", + "properties": { + "type": { + "enum": [ + "apiKey", + "http", + "mutualTLS", + "oauth2", + "openIdConnect" + ] + }, + "description": { + "type": "string" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-apikey" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http-bearer" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oauth2" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oidc" + } + ], + "unevaluatedProperties": false, + "$defs": { + "type-apikey": { + "if": { + "properties": { + "type": { + "const": "apiKey" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "cookie" + ] + } + }, + "required": [ + "name", + "in" + ] + } + }, + "type-http": { + "if": { + "properties": { + "type": { + "const": "http" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "scheme": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-http-bearer": { + "if": { + "properties": { + "type": { + "const": "http" + }, + "scheme": { + "const": "bearer" + } + }, + "required": [ + "type", + "scheme" + ] + }, + "then": { + "properties": { + "bearerFormat": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-oauth2": { + "if": { + "properties": { + "type": { + "const": "oauth2" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "flows": { + "$ref": "#/$defs/oauth-flows" + } + }, + "required": [ + "flows" + ] + } + }, + "type-oidc": { + "if": { + "properties": { + "type": { + "const": "openIdConnect" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "openIdConnectUrl": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "openIdConnectUrl" + ] + } + } + } + }, + "security-scheme-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/security-scheme" + } + }, + "oauth-flows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/$defs/oauth-flows/$defs/implicit" + }, + "password": { + "$ref": "#/$defs/oauth-flows/$defs/password" + }, + "clientCredentials": { + "$ref": "#/$defs/oauth-flows/$defs/client-credentials" + }, + "authorizationCode": { + "$ref": "#/$defs/oauth-flows/$defs/authorization-code" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "implicit": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "password": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "client-credentials": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "authorization-code": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + } + } + }, + "security-requirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "specification-extensions": { + "patternProperties": { + "^x-": true + } + }, + "examples": { + "properties": { + "example": true, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + } + } + }, + "uri": { + "type": "string", + "format": "uri" + }, + "map-of-strings": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } +} diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml new file mode 100644 index 0000000000..86cb44efca --- /dev/null +++ b/schemas/v3.1/schema.yaml @@ -0,0 +1,913 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +type: object +properties: + openapi: + type: string + pattern: '^3\.1\.\d+(-.+)?$' + info: + $ref: '#/$defs/info' + jsonSchemaDialect: + $ref: '#/$defs/uri' + default: 'https://spec.openapis.org/oas/3.1/dialect/base' + servers: + type: array + items: + $ref: '#/$defs/server' + paths: + $ref: '#/$defs/paths' + webhooks: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + components: + $ref: '#/$defs/components' + security: + type: array + items: + $ref: '#/$defs/security-requirement' + tags: + type: array + items: + $ref: '#/$defs/tag' + externalDocs: + $ref: '#/$defs/external-documentation' +required: + - openapi + - info +anyOf: + - required: + - paths + - required: + - components + - required: + - webhooks +$ref: '#/$defs/specification-extensions' +unevaluatedProperties: false + +$defs: + info: + type: object + properties: + title: + type: string + summary: + type: string + description: + type: string + termsOfService: + type: string + contact: + $ref: '#/$defs/contact' + license: + $ref: '#/$defs/license' + version: + type: string + required: + - title + - version + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + contact: + type: object + properties: + name: + type: string + url: + type: string + email: + type: string + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + license: + type: object + properties: + name: + type: string + identifier: + type: string + url: + $ref: '#/$defs/uri' + required: + - name + oneOf: + - required: + - identifier + - required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server: + type: object + properties: + url: + $ref: '#/$defs/uri' + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/$defs/server-variable' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server-variable: + type: object + properties: + enum: + type: array + items: + type: string + minItems: 1 + default: + type: string + descriptions: + type: string + required: + - default + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + components: + type: object + properties: + schemas: + type: object + additionalProperties: + $dynamicRef: '#meta' + responses: + type: object + additionalProperties: + $ref: '#/$defs/response-or-reference' + parameters: + type: object + additionalProperties: + $ref: '#/$defs/parameter-or-reference' + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + requestBodies: + type: object + additionalProperties: + $ref: '#/$defs/request-body-or-reference' + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + securitySchemes: + type: object + additionalProperties: + $ref: '#/$defs/security-scheme-or-reference' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + pathItems: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + patternProperties: + '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': + $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected + propertyNames: + pattern: '^[a-zA-Z0-9._-]+$' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + paths: + type: object + patternProperties: + '^/': + $ref: '#/$defs/path-item' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item: + type: object + properties: + summary: + type: string + description: + type: string + servers: + type: array + items: + $ref: '#/$defs/server' + parameters: + type: array + items: + $ref: '#/$defs/parameter-or-reference' + patternProperties: + '^(get|put|post|delete|options|head|patch|trace)$': + $ref: '#/$defs/operation' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/path-item' + + operation: + type: object + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + operationId: + type: string + parameters: + type: array + items: + $ref: '#/$defs/parameter-or-reference' + requestBody: + $ref: '#/$defs/request-body-or-reference' + responses: + $ref: '#/$defs/responses' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + deprecated: + default: false + type: boolean + security: + type: array + items: + $ref: '#/$defs/security-requirement' + servers: + type: array + items: + $ref: '#/$defs/server' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + external-documentation: + type: object + properties: + description: + type: string + url: + $ref: '#/$defs/uri' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter: + type: object + properties: + name: + type: string + in: + enum: + - query + - header + - path + - cookie + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + schema: + $dynamicRef: '#meta' + content: + $ref: '#/$defs/content' + required: + - in + oneOf: + - required: + - schema + - required: + - content + dependentSchemas: + schema: + properties: + style: + type: string + explode: + type: boolean + allowReserved: + default: false + type: boolean + allOf: + - $ref: '#/$defs/examples' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form' + + $defs: + styles-for-path: + if: + properties: + in: + const: path + required: + - in + then: + properties: + style: + default: simple + enum: + - matrix + - label + - simple + required: + const: true + required: + - required + + styles-for-header: + if: + properties: + in: + const: header + required: + - in + then: + properties: + style: + default: simple + enum: + - simple + + styles-for-query: + if: + properties: + in: + const: query + required: + - in + then: + properties: + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + + styles-for-cookie: + if: + properties: + in: + const: cookie + required: + - in + then: + properties: + style: + default: form + enum: + - form + + styles-for-form: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/parameter' + + request-body: + type: object + properties: + description: + type: string + content: + $ref: '#/$defs/content' + required: + default: false + type: boolean + required: + - content + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + request-body-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/request-body' + + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + propertyNames: + format: media-range + + media-type: + type: object + properties: + schema: + $dynamicRef: '#meta' + encoding: + type: object + additionalProperties: + $ref: '#/$defs/encoding' + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/examples' + unevaluatedProperties: false + + encoding: + type: object + properties: + contentType: + type: string + format: media-range + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + default: false + type: boolean + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/encoding/$defs/explode-default' + unevaluatedProperties: false + + $defs: + explode-default: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + responses: + type: object + properties: + default: + $ref: '#/$defs/response-or-reference' + patternProperties: + '^[1-5][0-9X]{2}$': + $ref: '#/$defs/response-or-reference' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response: + type: object + properties: + description: + type: string + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + content: + $ref: '#/$defs/content' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + required: + - description + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/response' + + callbacks: + type: object + $ref: '#/$defs/specification-extensions' + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + + callbacks-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/callbacks' + + example: + type: object + properties: + summary: + type: string + description: + type: string + value: true + externalValue: + $ref: '#/$defs/uri' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + example-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/example' + + link: + type: object + properties: + operationRef: + $ref: '#/$defs/uri' + operationId: true + parameters: + $ref: '#/$defs/map-of-strings' + requestBody: true + description: + type: string + body: + $ref: '#/$defs/server' + oneOf: + - required: + - operationRef + - required: + - operationId + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + link-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/link' + + header: + type: object + properties: + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + dependentSchemas: + schema: + properties: + style: + default: simple + enum: + - simple + explode: + default: false + type: boolean + allowReserved: + default: false + type: boolean + schema: + $dynamicRef: '#meta' + $ref: '#/$defs/examples' + content: + properties: + content: + $ref: '#/$defs/content' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + header-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/header' + + tag: + type: object + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + required: + - name + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + reference: + type: object + properties: + $ref: + $ref: '#/$defs/uri' + summary: + type: string + description: + type: string + unevaluatedProperties: false + + schema: + $dynamicAnchor: meta + type: + - object + - boolean + + security-scheme: + type: object + properties: + type: + enum: + - apiKey + - http + - mutualTLS + - oauth2 + - openIdConnect + description: + type: string + required: + - type + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/security-scheme/$defs/type-apikey' + - $ref: '#/$defs/security-scheme/$defs/type-http' + - $ref: '#/$defs/security-scheme/$defs/type-http-bearer' + - $ref: '#/$defs/security-scheme/$defs/type-oauth2' + - $ref: '#/$defs/security-scheme/$defs/type-oidc' + unevaluatedProperties: false + + $defs: + type-apikey: + if: + properties: + type: + const: apiKey + required: + - type + then: + properties: + name: + type: string + in: + enum: + - query + - header + - cookie + required: + - name + - in + + type-http: + if: + properties: + type: + const: http + required: + - type + then: + properties: + scheme: + type: string + required: + - scheme + + type-http-bearer: + if: + properties: + type: + const: http + scheme: + const: bearer + required: + - type + - scheme + then: + properties: + bearerFormat: + type: string + required: + - scheme + + type-oauth2: + if: + properties: + type: + const: oauth2 + required: + - type + then: + properties: + flows: + $ref: '#/$defs/oauth-flows' + required: + - flows + + type-oidc: + if: + properties: + type: + const: openIdConnect + required: + - type + then: + properties: + openIdConnectUrl: + $ref: '#/$defs/uri' + required: + - openIdConnectUrl + + security-scheme-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/security-scheme' + + oauth-flows: + type: object + properties: + implicit: + $ref: '#/$defs/oauth-flows/$defs/implicit' + password: + $ref: '#/$defs/oauth-flows/$defs/password' + clientCredentials: + $ref: '#/$defs/oauth-flows/$defs/client-credentials' + authorizationCode: + $ref: '#/$defs/oauth-flows/$defs/authorization-code' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + $defs: + implicit: + type: object + properties: + authorizationUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + password: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + client-credentials: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + authorization-code: + type: object + properties: + authorizationUrl: + type: string + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + security-requirement: + type: object + additionalProperties: + type: array + items: + type: string + + specification-extensions: + patternProperties: + '^x-': true + + examples: + properties: + example: true + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + + uri: + type: string + format: uri + + map-of-strings: + type: object + additionalProperties: + type: string diff --git a/scripts/validate.js b/scripts/validate.js new file mode 100755 index 0000000000..c9c70db797 --- /dev/null +++ b/scripts/validate.js @@ -0,0 +1,58 @@ +#!/usr/bin/env node + +const fs = require("fs"); +const yaml = require("yaml"); +const JsonSchema = require("@hyperjump/json-schema"); +const dialect = require("../schemas/v3.1/dialect/base.schema.json"); +const vocabulary = require("../schemas/v3.1/meta/base.schema.json"); + + +if (process.argv.length < 3) { + console.log("Usage: validate [--schema=schema] [--version=2021-03-02] [--format=BASIC] path-to-file.yaml"); + console.log("\t--schema: (Default: schema) The name of the yaml schema file to use"); + console.log("\t--version: (Default: 2021-03-02) The version of the yaml schema file to use"); + console.log("\t--format: (Default: BASIC) The JSON Schema output format to use. Options: FLAG, BASIC, DETAILED, VERBOSE"); + process.exit(1); +} + +const args = process.argv.reduce((acc, arg) => { + if (!arg.startsWith("--")) return acc; + + const [argName, argValue] = arg.substring(2).split("=", 2); + return { ...acc, [argName]: argValue }; +}, {}); + +(async function () { + try { + const schemaType = args.schema || "schema"; + const schemaVersion = args.version || "2021-03-02"; + const outputFormat = args.format || JsonSchema.BASIC; + + // Config + JsonSchema.setMetaOutputFormat(outputFormat); + //JsonSchema.setShouldMetaValidate(false); + + // Load schemas + JsonSchema.add(dialect); + JsonSchema.add(vocabulary); + fs.readdirSync(`${__dirname}/../schemas/v3.1`, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .map((entry) => fs.readFileSync(`${__dirname}/../schemas/v3.1/${entry.name}`, "utf8")) + .map((schemaYaml) => yaml.parse(schemaYaml)) + .forEach((schema) => JsonSchema.add(schema)); + + // Compile / meta-validate + const schema = await JsonSchema.get(`https://spec.openapis.org/oas/3.1/${schemaType}/${schemaVersion}`); + const validateSchema = await JsonSchema.validate(schema); + + // Validate instance + const instanceYaml = fs.readFileSync(`${process.cwd()}/${process.argv[process.argv.length - 1]}`, "utf8"); + const instance = yaml.parse(instanceYaml); + const results = validateSchema(instance, outputFormat); + console.log(JSON.stringify(results, null, " ")); + } catch (error) { + console.log("************* Error ***************"); + console.log(error); + console.log(JSON.stringify(error.output, null, " ")); + } +}()); diff --git a/scripts/yaml2json/yaml2json.js b/scripts/yaml2json/yaml2json.js new file mode 100755 index 0000000000..f69145ad36 --- /dev/null +++ b/scripts/yaml2json/yaml2json.js @@ -0,0 +1,30 @@ +#!/usr/bin/env node + +'use strict'; + +const fs = require('fs'); +const yaml = require('yaml'); + +function convert(filename) { + console.log(filename); + const s = fs.readFileSync(filename,'utf8'); + let obj; + try { + obj = yaml.parse(s, {prettyErrors: true}); + fs.writeFileSync(filename.replace('.yaml','.json'),JSON.stringify(obj,null,2),'utf8'); + } + catch (ex) { + console.warn(' ',ex.message); + process.exitCode = 1; + } +} + +if (process.argv.length<3) { + console.warn('Usage: yaml2json {infiles}'); +} +else { + for (let i=2;i
- If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
- If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
- For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
- If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
- If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
- For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
- If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
- If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
- For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
- If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
- If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
- For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. + +This object MAY be extended with [Specification Extensions](#specificationExtensions), though as noted, additional properties MAY omit the `x-` prefix within this object. + +###### Composition and Inheritance (Polymorphism) + +The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. +`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. + +While composition offers model extensibility, it does not imply a hierarchy between the models. +To support polymorphism, the OpenAPI Specification adds the `discriminator` field. +When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. +As such, the `discriminator` field MUST be a required field. +There are two ways to define the value of a discriminator for an inheriting instance. +- Use the schema name. +- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +###### XML Modeling + +The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. +The [XML Object](#xmlObject) contains additional information about the available options. + +###### Specifying Schema Dialects + +It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema. + +The `$schema` keyword MAY be present in any root Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. This allows use of Schema Objects which comply with other drafts of JSON Schema than the default Draft 2020-12 support. Tooling MUST support the OAS dialect schema id, and MAY support additional values of `$schema`. + +To allow use of a different default `$schema` value for all Schema Objects contained within an OAS document, a `jsonSchemaDialect` value may be set within the OpenAPI Object. If this default is not set, then the OAS dialect schema id MUST be used for these Schema Objects. The value of `$schema` within a Schema Object always overrides any default. + +When a Schema Object is referenced from an external resource which is not an OAS document (e.g. a bare JSON Schema resource), then the value of the `$schema` keyword for schemas within that resource MUST follow [JSON Schema rules](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.1.1). + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +type: object +required: +- name +properties: + name: + type: string + address: + $ref: '#/components/schemas/Address' + age: + type: integer + format: int32 + minimum: 0 +``` + +###### Model with Map/Dictionary Properties + +For a simple string to string mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "example": { + "name": "Puma", + "id": 1 + } +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +example: + name: Puma + id: 1 +``` + +###### Models with Composition + +```json +{ + "components": { + "schemas": { + "ErrorModel": { + "type": "object", + "required": [ + "message", + "code" + ], + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "integer", + "minimum": 100, + "maximum": 600 + } + } + }, + "ExtendedErrorModel": { + "allOf": [ + { + "$ref": "#/components/schemas/ErrorModel" + }, + { + "type": "object", + "required": [ + "rootCause" + ], + "properties": { + "rootCause": { + "type": "string" + } + } + } + ] + } + } + } +} +``` + +```yaml +components: + schemas: + ErrorModel: + type: object + required: + - message + - code + properties: + message: + type: string + code: + type: integer + minimum: 100 + maximum: 600 + ExtendedErrorModel: + allOf: + - $ref: '#/components/schemas/ErrorModel' + - type: object + required: + - rootCause + properties: + rootCause: + type: string +``` + +###### Models with Polymorphism Support + +```json +{ + "components": { + "schemas": { + "Pet": { + "type": "object", + "discriminator": { + "propertyName": "petType" + }, + "properties": { + "name": { + "type": "string" + }, + "petType": { + "type": "string" + } + }, + "required": [ + "name", + "petType" + ] + }, + "Cat": { + "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "huntingSkill": { + "type": "string", + "description": "The measured skill for hunting", + "default": "lazy", + "enum": [ + "clueless", + "lazy", + "adventurous", + "aggressive" + ] + } + }, + "required": [ + "huntingSkill" + ] + } + ] + }, + "Dog": { + "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "packSize": { + "type": "integer", + "format": "int32", + "description": "the size of the pack the dog is from", + "default": 0, + "minimum": 0 + } + }, + "required": [ + "packSize" + ] + } + ] + } + } + } +} +``` + +```yaml +components: + schemas: + Pet: + type: object + discriminator: + propertyName: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + Cat: ## "Cat" will be used as the discriminator value + description: A representation of a cat + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + huntingSkill: + type: string + description: The measured skill for hunting + enum: + - clueless + - lazy + - adventurous + - aggressive + required: + - huntingSkill + Dog: ## "Dog" will be used as the discriminator value + description: A representation of a dog + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + packSize: + type: integer + format: int32 + description: the size of the pack the dog is from + default: 0 + minimum: 0 + required: + - packSize +``` + +#### Discriminator Object + +When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. + +When using the discriminator, _inline_ schemas will not be considered. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. + mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. + +In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' +``` + +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: + + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' + discriminator: + propertyName: petType +``` + +The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: + +```json +{ + "id": 12345, + "petType": "Cat" +} +``` + +Will indicate that the `Cat` schema be used in conjunction with this payload. + +In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: + +```yaml +MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' + - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' + discriminator: + propertyName: petType + mapping: + dog: '#/components/schemas/Dog' + monster: 'https://gigantic-server.com/schemas/Monster/schema.json' +``` + +Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. + +When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. + +In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. + +For example: + +```yaml +components: + schemas: + Pet: + type: object + required: + - petType + properties: + petType: + type: string + discriminator: + propertyName: petType + mapping: + dog: Dog + Cat: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Cat` + properties: + name: + type: string + Dog: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Dog` + properties: + bark: + type: string + Lizard: + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + # all other properties specific to a `Lizard` + properties: + lovesRocks: + type: boolean +``` + +a payload like this: + +```json +{ + "petType": "Cat", + "name": "misty" +} +``` + +will indicate that the `Cat` schema be used. Likewise this schema: + +```json +{ + "petType": "dog", + "bark": "soft" +} +``` + +will map to `Dog` because of the definition in the `mapping` element. + + +#### XML Object + +A metadata object that allows for more fine-tuned XML model definitions. + +When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. +See examples for expected behavior. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. +namespace | `string` | The URI of the namespace definition. This MUST be in the form of an absolute URI. +prefix | `string` | The prefix to be used for the [name](#xmlName). +attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. +wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `