1# OpenAPI Specification 2 3#### Version 3.0.0 4 5The 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. 6 7This document is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). 8 9## Introduction 10 11The 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. 12 13An 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. 14 15## Table of Contents 16<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 --> 17 18- [Definitions](#definitions) 19 - [OpenAPI Document](#oasDocument) 20 - [Path Templating](#pathTemplating) 21 - [Media Types](#mediaTypes) 22 - [HTTP Status Codes](#httpCodes) 23- [Specification](#specification) 24 - [Versions](#versions) 25 - [Format](#format) 26 - [Document Structure](#documentStructure) 27 - [Data Types](#dataTypes) 28 - [Rich Text Formatting](#richText) 29 - [Relative References In URLs](#relativeReferences) 30 - [Schema](#schema) 31 - [OpenAPI Object](#oasObject) 32 - [Info Object](#infoObject) 33 - [Contact Object](#contactObject) 34 - [License Object](#licenseObject) 35 - [Server Object](#serverObject) 36 - [Server Variable Object](#serverVariableObject) 37 - [Components Object](#componentsObject) 38 - [Paths Object](#pathsObject) 39 - [Path Item Object](#pathItemObject) 40 - [Operation Object](#operationObject) 41 - [External Documentation Object](#externalDocumentationObject) 42 - [Parameter Object](#parameterObject) 43 - [Request Body Object](#requestBodyObject) 44 - [Media Type Object](#mediaTypeObject) 45 - [Encoding Object](#encodingObject) 46 - [Responses Object](#responsesObject) 47 - [Response Object](#responseObject) 48 - [Callback Object](#callbackObject) 49 - [Example Object](#exampleObject) 50 - [Link Object](#linkObject) 51 - [Header Object](#headerObject) 52 - [Tag Object](#tagObject) 53 - [Reference Object](#referenceObject) 54 - [Schema Object](#schemaObject) 55 - [Discriminator Object](#discriminatorObject) 56 - [XML Object](#xmlObject) 57 - [Security Scheme Object](#securitySchemeObject) 58 - [OAuth Flows Object](#oauthFlowsObject) 59 - [OAuth Flow Object](#oauthFlowObject) 60 - [Security Requirement Object](#securityRequirementObject) 61 - [Specification Extensions](#specificationExtensions) 62 - [Security Filtering](#securityFiltering) 63- [Appendix A: Revision History](#revisionHistory) 64 65 66<!-- /TOC --> 67 68## Definitions 69 70##### <a name="oasDocument"></a>OpenAPI Document 71A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. 72 73##### <a name="pathTemplating"></a>Path Templating 74Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. 75 76##### <a name="mediaTypes"></a>Media Types 77Media type definitions are spread across several resources. 78The media type definitions SHOULD be in compliance with [RFC6838](http://tools.ietf.org/html/rfc6838). 79 80Some examples of possible media type definitions: 81``` 82 text/plain; charset=utf-8 83 application/json 84 application/vnd.github+json 85 application/vnd.github.v3+json 86 application/vnd.github.v3.raw+json 87 application/vnd.github.v3.text+json 88 application/vnd.github.v3.html+json 89 application/vnd.github.v3.full+json 90 application/vnd.github.v3.diff 91 application/vnd.github.v3.patch 92``` 93##### <a name="httpCodes"></a>HTTP Status Codes 94The HTTP Status Codes are used to indicate the status of the executed operation. 95The available status codes are defined by [RFC7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). 96 97## Specification 98 99### Versions 100 101The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. 102 103The `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. 104 105Subsequent 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`. 106 107An 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"`.) 108 109### Format 110 111An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. 112 113For example, if a field has an array value, the JSON array representation will be used: 114 115```json 116{ 117 "field": [ 1, 2, 3 ] 118} 119``` 120All field names in the specification are **case sensitive**. 121 122The 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. 123 124Patterned fields MUST have unique names within the containing object. 125 126In 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: 127 128- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). 129- 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). 130 131**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. 132 133### <a name="documentStructure"></a>Document Structure 134 135An 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. 136 137It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. 138 139### <a name="dataTypes"></a>Data Types 140 141Primitive 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). 142Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. 143`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). 144Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. 145 146<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`. 147OAS uses several known formats to define in fine detail the data type being used. 148However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. 149Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification. 150Types 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. 151 152The formats defined by the OAS are: 153 154Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments 155----------- | ------ | -------- | -------- 156integer | `integer` | `int32` | signed 32 bits 157long | `integer` | `int64` | signed 64 bits 158float | `number` | `float` | | 159double | `number` | `double` | | 160string | `string` | | | 161byte | `string` | `byte` | base64 encoded characters 162binary | `string` | `binary` | any sequence of octets 163boolean | `boolean` | | | 164date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) 165dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) 166password | `string` | `password` | A hint to UIs to obscure input. 167 168### <a name="richText"></a>Rich Text Formatting 169Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. 170Where 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. 171 172### <a name="relativeReferences"></a>Relative References in URLs 173 174Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). 175Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. 176 177Relative 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). 178 179### Schema 180 181In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. 182 183#### <a name="oasObject"></a>OpenAPI Object 184 185This is the root document object of the [OpenAPI document](#oasDocument). 186 187##### Fixed Fields 188 189Field Name | Type | Description 190---|:---:|--- 191<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://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. 192<a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. 193<a name="oasServers"></a>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 `/`. 194<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. 195<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. 196<a name="oasSecurity"></a>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. 197<a name="oasTags"></a>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. 198<a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. 199 200This object MAY be extended with [Specification Extensions](#specificationExtensions). 201 202#### <a name="infoObject"></a>Info Object 203 204The object provides metadata about the API. 205The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. 206 207##### Fixed Fields 208 209Field Name | Type | Description 210---|:---:|--- 211<a name="infoTitle"></a>title | `string` | **REQUIRED**. The title of the application. 212<a name="infoDescription"></a>description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 213<a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. 214<a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API. 215<a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API. 216<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). 217 218 219This object MAY be extended with [Specification Extensions](#specificationExtensions). 220 221##### Info Object Example: 222 223```json 224{ 225 "title": "Sample Pet Store App", 226 "description": "This is a sample server for a pet store.", 227 "termsOfService": "http://example.com/terms/", 228 "contact": { 229 "name": "API Support", 230 "url": "http://www.example.com/support", 231 "email": "support@example.com" 232 }, 233 "license": { 234 "name": "Apache 2.0", 235 "url": "http://www.apache.org/licenses/LICENSE-2.0.html" 236 }, 237 "version": "1.0.1" 238} 239``` 240 241```yaml 242title: Sample Pet Store App 243description: This is a sample server for a pet store. 244termsOfService: http://example.com/terms/ 245contact: 246 name: API Support 247 url: http://www.example.com/support 248 email: support@example.com 249license: 250 name: Apache 2.0 251 url: http://www.apache.org/licenses/LICENSE-2.0.html 252version: 1.0.1 253``` 254 255#### <a name="contactObject"></a>Contact Object 256 257Contact information for the exposed API. 258 259##### Fixed Fields 260 261Field Name | Type | Description 262---|:---:|--- 263<a name="contactName"></a>name | `string` | The identifying name of the contact person/organization. 264<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. 265<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. 266 267This object MAY be extended with [Specification Extensions](#specificationExtensions). 268 269##### Contact Object Example: 270 271```json 272{ 273 "name": "API Support", 274 "url": "http://www.example.com/support", 275 "email": "support@example.com" 276} 277``` 278 279```yaml 280name: API Support 281url: http://www.example.com/support 282email: support@example.com 283``` 284 285#### <a name="licenseObject"></a>License Object 286 287License information for the exposed API. 288 289##### Fixed Fields 290 291Field Name | Type | Description 292---|:---:|--- 293<a name="licenseName"></a>name | `string` | **REQUIRED**. The license name used for the API. 294<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. MUST be in the format of a URL. 295 296This object MAY be extended with [Specification Extensions](#specificationExtensions). 297 298##### License Object Example: 299 300```json 301{ 302 "name": "Apache 2.0", 303 "url": "http://www.apache.org/licenses/LICENSE-2.0.html" 304} 305``` 306 307```yaml 308name: Apache 2.0 309url: http://www.apache.org/licenses/LICENSE-2.0.html 310``` 311 312#### <a name="serverObject"></a>Server Object 313 314An object representing a Server. 315 316##### Fixed Fields 317 318Field Name | Type | Description 319---|:---:|--- 320<a name="serverUrl"></a>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`}`. 321<a name="serverDescription"></a>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. 322<a name="serverVariables"></a>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. 323 324This object MAY be extended with [Specification Extensions](#specificationExtensions). 325 326##### Server Object Example 327 328A single server would be described as: 329 330```json 331{ 332 "url": "https://development.gigantic-server.com/v1", 333 "description": "Development server" 334} 335``` 336 337```yaml 338url: https://development.gigantic-server.com/v1 339description: Development server 340``` 341 342The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): 343 344```json 345{ 346 "servers": [ 347 { 348 "url": "https://development.gigantic-server.com/v1", 349 "description": "Development server" 350 }, 351 { 352 "url": "https://staging.gigantic-server.com/v1", 353 "description": "Staging server" 354 }, 355 { 356 "url": "https://api.gigantic-server.com/v1", 357 "description": "Production server" 358 } 359 ] 360} 361``` 362 363```yaml 364servers: 365- url: https://development.gigantic-server.com/v1 366 description: Development server 367- url: https://staging.gigantic-server.com/v1 368 description: Staging server 369- url: https://api.gigantic-server.com/v1 370 description: Production server 371``` 372 373The following shows how variables can be used for a server configuration: 374 375```json 376{ 377 "servers": [ 378 { 379 "url": "https://{username}.gigantic-server.com:{port}/{basePath}", 380 "description": "The production API server", 381 "variables": { 382 "username": { 383 "default": "demo", 384 "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" 385 }, 386 "port": { 387 "enum": [ 388 "8443", 389 "443" 390 ], 391 "default": "8443" 392 }, 393 "basePath": { 394 "default": "v2" 395 } 396 } 397 } 398 ] 399} 400``` 401 402```yaml 403servers: 404- url: https://{username}.gigantic-server.com:{port}/{basePath} 405 description: The production API server 406 variables: 407 username: 408 # note! no enum here means it is an open value 409 default: demo 410 description: this value is assigned by the service provider, in this example `gigantic-server.com` 411 port: 412 enum: 413 - '8443' 414 - '443' 415 default: '8443' 416 basePath: 417 # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` 418 default: v2 419``` 420 421 422#### <a name="serverVariableObject"></a>Server Variable Object 423 424An object representing a Server Variable for server URL template substitution. 425 426##### Fixed Fields 427 428Field Name | Type | Description 429---|:---:|--- 430<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. 431<a name="serverVariableDefault"></a>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. 432<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 433 434This object MAY be extended with [Specification Extensions](#specificationExtensions). 435 436#### <a name="componentsObject"></a>Components Object 437 438Holds a set of reusable objects for different aspects of the OAS. 439All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. 440 441 442##### Fixed Fields 443 444Field Name | Type | Description 445---|:---|--- 446<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). 447<a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). 448<a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). 449<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). 450<a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). 451<a name="componentsHeaders"></a> headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). 452<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). 453<a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). 454<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). 455 456This object MAY be extended with [Specification Extensions](#specificationExtensions). 457 458All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. 459 460Field Name Examples: 461 462``` 463User 464User_1 465User_Name 466user-name 467my.org.User 468``` 469 470##### Components Object Example 471 472```json 473"components": { 474 "schemas": { 475 "Category": { 476 "type": "object", 477 "properties": { 478 "id": { 479 "type": "integer", 480 "format": "int64" 481 }, 482 "name": { 483 "type": "string" 484 } 485 } 486 }, 487 "Tag": { 488 "type": "object", 489 "properties": { 490 "id": { 491 "type": "integer", 492 "format": "int64" 493 }, 494 "name": { 495 "type": "string" 496 } 497 } 498 } 499 }, 500 "parameters": { 501 "skipParam": { 502 "name": "skip", 503 "in": "query", 504 "description": "number of items to skip", 505 "required": true, 506 "schema": { 507 "type": "integer", 508 "format": "int32" 509 } 510 }, 511 "limitParam": { 512 "name": "limit", 513 "in": "query", 514 "description": "max records to return", 515 "required": true, 516 "schema" : { 517 "type": "integer", 518 "format": "int32" 519 } 520 } 521 }, 522 "responses": { 523 "NotFound": { 524 "description": "Entity not found." 525 }, 526 "IllegalInput": { 527 "description": "Illegal input for operation." 528 }, 529 "GeneralError": { 530 "description": "General Error", 531 "content": { 532 "application/json": { 533 "schema": { 534 "$ref": "#/components/schemas/GeneralError" 535 } 536 } 537 } 538 } 539 }, 540 "securitySchemes": { 541 "api_key": { 542 "type": "apiKey", 543 "name": "api_key", 544 "in": "header" 545 }, 546 "petstore_auth": { 547 "type": "oauth2", 548 "flows": { 549 "implicit": { 550 "authorizationUrl": "http://example.org/api/oauth/dialog", 551 "scopes": { 552 "write:pets": "modify pets in your account", 553 "read:pets": "read your pets" 554 } 555 } 556 } 557 } 558 } 559} 560``` 561 562```yaml 563components: 564 schemas: 565 Category: 566 type: object 567 properties: 568 id: 569 type: integer 570 format: int64 571 name: 572 type: string 573 Tag: 574 type: object 575 properties: 576 id: 577 type: integer 578 format: int64 579 name: 580 type: string 581 parameters: 582 skipParam: 583 name: skip 584 in: query 585 description: number of items to skip 586 required: true 587 schema: 588 type: integer 589 format: int32 590 limitParam: 591 name: limit 592 in: query 593 description: max records to return 594 required: true 595 schema: 596 type: integer 597 format: int32 598 responses: 599 NotFound: 600 description: Entity not found. 601 IllegalInput: 602 description: Illegal input for operation. 603 GeneralError: 604 description: General Error 605 content: 606 application/json: 607 schema: 608 $ref: '#/components/schemas/GeneralError' 609 securitySchemes: 610 api_key: 611 type: apiKey 612 name: api_key 613 in: header 614 petstore_auth: 615 type: oauth2 616 flows: 617 implicit: 618 authorizationUrl: http://example.org/api/oauth/dialog 619 scopes: 620 write:pets: modify pets in your account 621 read:pets: read your pets 622``` 623 624 625#### <a name="pathsObject"></a>Paths Object 626 627Holds the relative paths to the individual endpoints and their operations. 628The 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). 629 630##### Patterned Fields 631 632Field Pattern | Type | Description 633---|:---:|--- 634<a name="pathsPath"></a>/{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. 635 636This object MAY be extended with [Specification Extensions](#specificationExtensions). 637 638##### Path Templating Matching 639 640Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: 641 642``` 643 /pets/{petId} 644 /pets/mine 645``` 646 647The following paths are considered identical and invalid: 648 649``` 650 /pets/{petId} 651 /pets/{name} 652``` 653 654The following may lead to ambiguous resolution: 655 656``` 657 /{entity}/me 658 /books/{id} 659``` 660 661##### Paths Object Example 662 663```json 664{ 665 "/pets": { 666 "get": { 667 "description": "Returns all pets from the system that the user has access to", 668 "responses": { 669 "200": { 670 "description": "A list of pets.", 671 "content": { 672 "application/json": { 673 "schema": { 674 "type": "array", 675 "items": { 676 "$ref": "#/components/schemas/pet" 677 } 678 } 679 } 680 } 681 } 682 } 683 } 684 } 685} 686``` 687 688```yaml 689/pets: 690 get: 691 description: Returns all pets from the system that the user has access to 692 responses: 693 '200': 694 description: A list of pets. 695 content: 696 application/json: 697 schema: 698 type: array 699 items: 700 $ref: '#/components/schemas/pet' 701``` 702 703#### <a name="pathItemObject"></a>Path Item Object 704 705Describes the operations available on a single path. 706A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). 707The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. 708 709##### Fixed Fields 710 711Field Name | Type | Description 712---|:---:|--- 713<a name="pathItemRef"></a>$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*. 714<a name="pathItemSummary"></a>summary| `string` | An optional, string summary, intended to apply to all operations in this path. 715<a name="pathItemDescription"></a>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. 716<a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path. 717<a name="pathItemPut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. 718<a name="pathItemPost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path. 719<a name="pathItemDelete"></a>delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. 720<a name="pathItemOptions"></a>options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. 721<a name="pathItemHead"></a>head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. 722<a name="pathItemPatch"></a>patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. 723<a name="pathItemTrace"></a>trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. 724<a name="pathItemServers"></a>servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. 725<a name="pathItemParameters"></a>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). 726 727 728This object MAY be extended with [Specification Extensions](#specificationExtensions). 729 730##### Path Item Object Example 731 732```json 733{ 734 "get": { 735 "description": "Returns pets based on ID", 736 "summary": "Find pets by ID", 737 "operationId": "getPetsById", 738 "responses": { 739 "200": { 740 "description": "pet response", 741 "content": { 742 "*/*": { 743 "schema": { 744 "type": "array", 745 "items": { 746 "$ref": "#/components/schemas/Pet" 747 } 748 } 749 } 750 } 751 }, 752 "default": { 753 "description": "error payload", 754 "content": { 755 "text/html": { 756 "schema": { 757 "$ref": "#/components/schemas/ErrorModel" 758 } 759 } 760 } 761 } 762 } 763 }, 764 "parameters": [ 765 { 766 "name": "id", 767 "in": "path", 768 "description": "ID of pet to use", 769 "required": true, 770 "schema": { 771 "type": "array", 772 "items": { 773 "type": "string" 774 } 775 }, 776 "style": "simple" 777 } 778 ] 779} 780``` 781 782```yaml 783get: 784 description: Returns pets based on ID 785 summary: Find pets by ID 786 operationId: getPetsById 787 responses: 788 '200': 789 description: pet response 790 content: 791 '*/*' : 792 schema: 793 type: array 794 items: 795 $ref: '#/components/schemas/Pet' 796 default: 797 description: error payload 798 content: 799 'text/html': 800 schema: 801 $ref: '#/components/schemas/ErrorModel' 802parameters: 803- name: id 804 in: path 805 description: ID of pet to use 806 required: true 807 schema: 808 type: array 809 style: simple 810 items: 811 type: string 812``` 813 814#### <a name="operationObject"></a>Operation Object 815 816Describes a single API operation on a path. 817 818##### Fixed Fields 819 820Field Name | Type | Description 821---|:---:|--- 822<a name="operationTags"></a>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. 823<a name="operationSummary"></a>summary | `string` | A short summary of what the operation does. 824<a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 825<a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. 826<a name="operationId"></a>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. 827<a name="operationParameters"></a>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). 828<a name="operationRequestBody"></a>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. 829<a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. 830<a name="operationCallbacks"></a>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. 831<a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. 832<a name="operationSecurity"></a>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. 833<a name="operationServers"></a>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. 834 835This object MAY be extended with [Specification Extensions](#specificationExtensions). 836 837##### Operation Object Example 838 839```json 840{ 841 "tags": [ 842 "pet" 843 ], 844 "summary": "Updates a pet in the store with form data", 845 "operationId": "updatePetWithForm", 846 "parameters": [ 847 { 848 "name": "petId", 849 "in": "path", 850 "description": "ID of pet that needs to be updated", 851 "required": true, 852 "schema": { 853 "type": "string" 854 } 855 } 856 ], 857 "requestBody": { 858 "content": { 859 "application/x-www-form-urlencoded": { 860 "schema": { 861 "type": "object", 862 "properties": { 863 "name": { 864 "description": "Updated name of the pet", 865 "type": "string" 866 }, 867 "status": { 868 "description": "Updated status of the pet", 869 "type": "string" 870 } 871 }, 872 "required": ["status"] 873 } 874 } 875 } 876 }, 877 "responses": { 878 "200": { 879 "description": "Pet updated.", 880 "content": { 881 "application/json": {}, 882 "application/xml": {} 883 } 884 }, 885 "405": { 886 "description": "Invalid input", 887 "content": { 888 "application/json": {}, 889 "application/xml": {} 890 } 891 } 892 }, 893 "security": [ 894 { 895 "petstore_auth": [ 896 "write:pets", 897 "read:pets" 898 ] 899 } 900 ] 901} 902``` 903 904```yaml 905tags: 906- pet 907summary: Updates a pet in the store with form data 908operationId: updatePetWithForm 909parameters: 910- name: petId 911 in: path 912 description: ID of pet that needs to be updated 913 required: true 914 schema: 915 type: string 916requestBody: 917 content: 918 'application/x-www-form-urlencoded': 919 schema: 920 properties: 921 name: 922 description: Updated name of the pet 923 type: string 924 status: 925 description: Updated status of the pet 926 type: string 927 required: 928 - status 929responses: 930 '200': 931 description: Pet updated. 932 content: 933 'application/json': {} 934 'application/xml': {} 935 '405': 936 description: Invalid input 937 content: 938 'application/json': {} 939 'application/xml': {} 940security: 941- petstore_auth: 942 - write:pets 943 - read:pets 944``` 945 946 947#### <a name="externalDocumentationObject"></a>External Documentation Object 948 949Allows referencing an external resource for extended documentation. 950 951##### Fixed Fields 952 953Field Name | Type | Description 954---|:---:|--- 955<a name="externalDocDescription"></a>description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 956<a name="externalDocUrl"></a>url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. 957 958This object MAY be extended with [Specification Extensions](#specificationExtensions). 959 960##### External Documentation Object Example 961 962```json 963{ 964 "description": "Find more info here", 965 "url": "https://example.com" 966} 967``` 968 969```yaml 970description: Find more info here 971url: https://example.com 972``` 973 974#### <a name="parameterObject"></a>Parameter Object 975 976Describes a single operation parameter. 977 978A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). 979 980##### Parameter Locations 981There are four possible parameter locations specified by the `in` field: 982* 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`. 983* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. 984* 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. 985* cookie - Used to pass a specific cookie value to the API. 986 987 988##### Fixed Fields 989Field Name | Type | Description 990---|:---:|--- 991<a name="parameterName"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. <ul><li>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.<li>If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.</ul> 992<a name="parameterIn"></a>in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie". 993<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 994<a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is "path", this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 995<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. 996<a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. 997 998The rules for serialization of the parameter are specified in one of two ways. 999For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. 1000 1001Field Name | Type | Description 1002---|:---:|--- 1003<a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`. 1004<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. 1005<a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`. 1006<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. 1007<a name="parameterExample"></a>example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` object is mutually exclusive of the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary. 1008<a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` object is mutually exclusive of the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 1009 1010For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. 1011A parameter MUST contain either a `schema` property, or a `content` property, but not both. 1012When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. 1013 1014 1015Field Name | Type | Description 1016---|:---:|--- 1017<a name="parameterContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. 1018 1019##### Style Values 1020 1021In order to support common ways of serializing simple parameters, a set of `style` values are defined. 1022 1023`style` | [`type`](#dataTypes) | `in` | Comments 1024----------- | ------ | -------- | -------- 1025matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) 1026label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) 1027form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0. 1028simple | `array` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0. 1029spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. 1030pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. 1031deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. 1032 1033 1034##### Style Examples 1035 1036Assume a parameter named `color` has one of the following values: 1037 1038``` 1039 string -> "blue" 1040 array -> ["blue","black","brown"] 1041 object -> { "R": 100, "G": 200, "B": 150 } 1042``` 1043The following table shows examples of rendering differences for each value. 1044 1045[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` 1046----------- | ------ | -------- | -------- | --------|------- 1047matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 1048matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 1049label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 1050label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 1051form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 1052form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 1053simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 1054simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 1055spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 1056pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 1057deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 1058 1059This object MAY be extended with [Specification Extensions](#specificationExtensions). 1060 1061##### Parameter Object Examples 1062 1063A header parameter with an array of 64 bit integer numbers: 1064 1065```json 1066{ 1067 "name": "token", 1068 "in": "header", 1069 "description": "token to be passed as a header", 1070 "required": true, 1071 "schema": { 1072 "type": "array", 1073 "items": { 1074 "type": "integer", 1075 "format": "int64" 1076 } 1077 }, 1078 "style": "simple" 1079} 1080``` 1081 1082```yaml 1083name: token 1084in: header 1085description: token to be passed as a header 1086required: true 1087schema: 1088 type: array 1089 items: 1090 type: integer 1091 format: int64 1092style: simple 1093``` 1094 1095A path parameter of a string value: 1096```json 1097{ 1098 "name": "username", 1099 "in": "path", 1100 "description": "username to fetch", 1101 "required": true, 1102 "schema": { 1103 "type": "string" 1104 } 1105} 1106``` 1107 1108```yaml 1109name: username 1110in: path 1111description: username to fetch 1112required: true 1113schema: 1114 type: string 1115``` 1116 1117An optional query parameter of a string value, allowing multiple values by repeating the query parameter: 1118```json 1119{ 1120 "name": "id", 1121 "in": "query", 1122 "description": "ID of the object to fetch", 1123 "required": false, 1124 "schema": { 1125 "type": "array", 1126 "items": { 1127 "type": "string" 1128 } 1129 }, 1130 "style": "form", 1131 "explode": true 1132} 1133``` 1134 1135```yaml 1136name: id 1137in: query 1138description: ID of the object to fetch 1139required: false 1140schema: 1141 type: array 1142 items: 1143 type: string 1144style: form 1145explode: true 1146``` 1147 1148A free-form query parameter, allowing undefined parameters of a specific type: 1149```json 1150{ 1151 "in": "query", 1152 "name": "freeForm", 1153 "schema": { 1154 "type": "object", 1155 "additionalProperties": { 1156 "type": "integer" 1157 }, 1158 }, 1159 "style": "form" 1160} 1161``` 1162 1163```yaml 1164in: query 1165name: freeForm 1166schema: 1167 type: object 1168 additionalProperties: 1169 type: integer 1170style: form 1171``` 1172 1173A complex parameter using `content` to define serialization: 1174 1175```json 1176{ 1177 "in": "query", 1178 "name": "coordinates", 1179 "content": { 1180 "application/json": { 1181 "schema": { 1182 "type": "object", 1183 "required": [ 1184 "lat", 1185 "long" 1186 ], 1187 "properties": { 1188 "lat": { 1189 "type": "number" 1190 }, 1191 "long": { 1192 "type": "number" 1193 } 1194 } 1195 } 1196 } 1197 } 1198} 1199``` 1200 1201```yaml 1202in: query 1203name: coordinates 1204content: 1205 application/json: 1206 schema: 1207 type: object 1208 required: 1209 - lat 1210 - long 1211 properties: 1212 lat: 1213 type: number 1214 long: 1215 type: number 1216``` 1217 1218#### <a name="requestBodyObject"></a>Request Body Object 1219 1220Describes a single request body. 1221 1222##### Fixed Fields 1223Field Name | Type | Description 1224---|:---:|--- 1225<a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 1226<a name="requestBodyContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | **REQUIRED**. The content of the request body. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For requests that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* 1227<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. 1228 1229 1230This object MAY be extended with [Specification Extensions](#specificationExtensions). 1231 1232##### Request Body Examples 1233 1234A request body with a referenced model definition. 1235```json 1236{ 1237 "description": "user to add to the system", 1238 "content": { 1239 "application/json": { 1240 "schema": { 1241 "$ref": "#/components/schemas/User" 1242 }, 1243 "examples": { 1244 "user" : { 1245 "summary": "User Example", 1246 "externalValue": "http://foo.bar/examples/user-example.json" 1247 } 1248 } 1249 }, 1250 "application/xml": { 1251 "schema": { 1252 "$ref": "#/components/schemas/User" 1253 }, 1254 "examples": { 1255 "user" : { 1256 "summary": "User example in XML", 1257 "externalValue": "http://foo.bar/examples/user-example.xml" 1258 } 1259 } 1260 }, 1261 "text/plain": { 1262 "examples": { 1263 "user" : { 1264 "summary": "User example in Plain text", 1265 "externalValue": "http://foo.bar/examples/user-example.txt" 1266 } 1267 } 1268 }, 1269 "*/*": { 1270 "examples": { 1271 "user" : { 1272 "summary": "User example in other format", 1273 "externalValue": "http://foo.bar/examples/user-example.whatever" 1274 } 1275 } 1276 } 1277 } 1278} 1279``` 1280 1281```yaml 1282description: user to add to the system 1283content: 1284 'application/json': 1285 schema: 1286 $ref: '#/components/schemas/User' 1287 examples: 1288 user: 1289 summary: User Example 1290 externalValue: 'http://foo.bar/examples/user-example.json' 1291 'application/xml': 1292 schema: 1293 $ref: '#/components/schemas/User' 1294 examples: 1295 user: 1296 summary: User Example in XML 1297 externalValue: 'http://foo.bar/examples/user-example.xml' 1298 'text/plain': 1299 examples: 1300 user: 1301 summary: User example in text plain format 1302 externalValue: 'http://foo.bar/examples/user-example.txt' 1303 '*/*': 1304 examples: 1305 user: 1306 summary: User example in other format 1307 externalValue: 'http://foo.bar/examples/user-example.whatever' 1308``` 1309 1310A body parameter that is an array of string values: 1311```json 1312{ 1313 "description": "user to add to the system", 1314 "content": { 1315 "text/plain": { 1316 "schema": { 1317 "type": "array", 1318 "items": { 1319 "type": "string" 1320 } 1321 } 1322 } 1323 } 1324} 1325``` 1326 1327```yaml 1328description: user to add to the system 1329required: true 1330content: 1331 text/plain: 1332 schema: 1333 type: array 1334 items: 1335 type: string 1336``` 1337 1338 1339#### <a name="mediaTypeObject"></a>Media Type Object 1340Each Media Type Object provides schema and examples for the media type identified by its key. 1341 1342##### Fixed Fields 1343Field Name | Type | Description 1344---|:---:|--- 1345<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. 1346<a name="mediaTypeExample"></a>example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` object is mutually exclusive of the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. 1347<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` object is mutually exclusive of the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 1348<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`. 1349 1350This object MAY be extended with [Specification Extensions](#specificationExtensions). 1351 1352##### Media Type Examples 1353 1354```js 1355{ 1356 "application/json": { 1357 "schema": { 1358 "$ref": "#/components/schemas/Pet" 1359 }, 1360 "examples": { 1361 "cat" : { 1362 "summary": "An example of a cat", 1363 "value": 1364 { 1365 "name": "Fluffy", 1366 "petType": "Cat", 1367 "color": "White", 1368 "gender": "male", 1369 "breed": "Persian" 1370 } 1371 }, 1372 "dog": { 1373 "summary": "An example of a dog with a cat's name", 1374 "value" : { 1375 "name": "Puma", 1376 "petType": "Dog", 1377 "color": "Black", 1378 "gender": "Female", 1379 "breed": "Mixed" 1380 }, 1381 "frog": { 1382 "$ref": "#/components/examples/frog-example" 1383 } 1384 } 1385 } 1386 } 1387} 1388``` 1389 1390```yaml 1391application/json: 1392 schema: 1393 $ref: "#/components/schemas/Pet" 1394 examples: 1395 cat: 1396 summary: An example of a cat 1397 value: 1398 name: Fluffy 1399 petType: Cat 1400 color: White 1401 gender: male 1402 breed: Persian 1403 dog: 1404 summary: An example of a dog with a cat's name 1405 value: 1406 name: Puma 1407 petType: Dog 1408 color: Black 1409 gender: Female 1410 breed: Mixed 1411 frog: 1412 $ref: "#/components/examples/frog-example" 1413``` 1414 1415##### Considerations for File Uploads 1416 1417In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically: 1418 1419```yaml 1420# content transferred with base64 encoding 1421schema: 1422 type: string 1423 format: base64 1424``` 1425 1426```yaml 1427# content transferred in binary (octet-stream): 1428schema: 1429 type: string 1430 format: binary 1431``` 1432 1433These examples apply to either input payloads of file uploads or response payloads. 1434 1435A `requestBody` for submitting a file in a `POST` operation may look like the following example: 1436 1437```yaml 1438requestBody: 1439 content: 1440 application/octet-stream: 1441 # any media type is accepted, functionally equivalent to `*/*` 1442 schema: 1443 # a binary file of any type 1444 type: string 1445 format: binary 1446``` 1447 1448In addition, specific media types MAY be specified: 1449 1450```yaml 1451# multiple, specific media types may be specified: 1452requestBody: 1453 content: 1454 # a binary file of type png or jpeg 1455 'image/jpeg': 1456 schema: 1457 type: string 1458 format: binary 1459 'image/png': 1460 schema: 1461 type: string 1462 format: binary 1463``` 1464 1465To upload multiple files, a `multipart` media type MUST be used: 1466 1467```yaml 1468requestBody: 1469 content: 1470 multipart/form-data: 1471 schema: 1472 properties: 1473 # The property name 'file' will be used for all files. 1474 file: 1475 type: array 1476 items: 1477 type: string 1478 format: binary 1479 1480``` 1481 1482##### Support for x-www-form-urlencoded Request Bodies 1483 1484To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following 1485definition may be used: 1486 1487```yaml 1488requestBody: 1489 content: 1490 application/x-www-form-urlencoded: 1491 schema: 1492 type: object 1493 properties: 1494 id: 1495 type: string 1496 format: uuid 1497 address: 1498 # complex types are stringified to support RFC 1866 1499 type: object 1500 properties: {} 1501``` 1502 1503In this example, the contents in the `requestBody` MUST be stringified per [RFC1866](https://tools.ietf.org/html/rfc1866/) when passed to the server. In addition, the `address` field complex object will be stringified. 1504 1505When passing complex objects in the `application/x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [`Encoding Object`](#encodingObject)'s [`style`](#encodingStyle) property as `form`. 1506 1507##### Special Considerations for `multipart` Content 1508 1509It is common to use `multipart/form-data` as a `Content-Type` when transferring request bodies to operations. In contrast to 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content. This supports complex structures as well as supporting mechanisms for multiple file uploads. 1510 1511When passing in `multipart` types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default `Content-Type`s are defined for `multipart`: 1512 1513* If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` 1514* If the property is complex, or an array of complex values, the default Content-Type is `application/json` 1515* If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream` 1516 1517 1518Examples: 1519 1520```yaml 1521requestBody: 1522 content: 1523 multipart/form-data: 1524 schema: 1525 type: object 1526 properties: 1527 id: 1528 type: string 1529 format: uuid 1530 address: 1531 # default Content-Type for objects is `application/json` 1532 type: object 1533 properties: {} 1534 profileImage: 1535 # default Content-Type for string/binary is `application/octet-stream` 1536 type: string 1537 format: binary 1538 children: 1539 # default Content-Type for arrays is based on the `inner` type (text/plain here) 1540 type: array 1541 items: 1542 type: string 1543 addresses: 1544 # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) 1545 type: array 1546 items: 1547 type: '#/components/schemas/Address' 1548``` 1549 1550An `encoding` attribute is introduced to give you control over the serialization of parts of `multipart` request bodies. This attribute is _only_ applicable to `multipart` and `application/x-www-form-urlencoded` request bodies. 1551 1552#### <a name="encodingObject"></a>Encoding Object 1553 1554A single encoding definition applied to a single schema property. 1555 1556##### Fixed Fields 1557Field Name | Type | Description 1558---|:---:|--- 1559<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types. 1560<a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | A map allowing additional information to be provided as headers, for example `Content-Disposition`. `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`. 1561<a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`. 1562<a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`. 1563<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`. 1564 1565This object MAY be extended with [Specification Extensions](#specificationExtensions). 1566 1567##### Encoding Object Example 1568 1569```yaml 1570requestBody: 1571 content: 1572 multipart/mixed: 1573 schema: 1574 type: object 1575 properties: 1576 id: 1577 # default is text/plain 1578 type: string 1579 format: uuid 1580 address: 1581 # default is application/json 1582 type: object 1583 properties: {} 1584 historyMetadata: 1585 # need to declare XML format! 1586 description: metadata in XML format 1587 type: object 1588 properties: {} 1589 profileImage: 1590 # default is application/octet-stream, need to declare an image type only! 1591 type: string 1592 format: binary 1593 encoding: 1594 historyMetadata: 1595 # require XML Content-Type in utf-8 encoding 1596 contentType: application/xml; charset=utf-8 1597 profileImage: 1598 # only accept png/jpeg 1599 contentType: image/png, image/jpeg 1600 headers: 1601 X-Rate-Limit-Limit: 1602 description: The number of allowed requests in the current period 1603 schema: 1604 type: integer 1605``` 1606 1607#### <a name="responsesObject"></a>Responses Object 1608 1609A container for the expected responses of an operation. 1610The container maps a HTTP response code to the expected response. 1611 1612The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. 1613However, documentation is expected to cover a successful operation response and any known errors. 1614 1615The `default` MAY be used as a default response object for all HTTP codes 1616that are not covered individually by the specification. 1617 1618The `Responses Object` MUST contain at least one response code, and it 1619SHOULD be the response for a successful operation call. 1620 1621##### Fixed Fields 1622Field Name | Type | Description 1623---|:---:|--- 1624<a name="responsesDefault"></a>default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A [Reference Object](#referenceObject) can link to a response that the [OpenAPI Object's components/responses](#componentsResponses) section defines. 1625 1626##### Patterned Fields 1627Field Pattern | Type | Description 1628---|:---:|--- 1629<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. 1630 1631 1632This object MAY be extended with [Specification Extensions](#specificationExtensions). 1633 1634##### Responses Object Example 1635 1636A 200 response for a successful operation and a default response for others (implying an error): 1637 1638```json 1639{ 1640 "200": { 1641 "description": "a pet to be returned", 1642 "content": { 1643 "application/json": { 1644 "schema": { 1645 "$ref": "#/components/schemas/Pet" 1646 } 1647 } 1648 } 1649 }, 1650 "default": { 1651 "description": "Unexpected error", 1652 "content": { 1653 "application/json": { 1654 "schema": { 1655 "$ref": "#/components/schemas/ErrorModel" 1656 } 1657 } 1658 } 1659 } 1660} 1661``` 1662 1663```yaml 1664'200': 1665 description: a pet to be returned 1666 content: 1667 application/json: 1668 schema: 1669 $ref: '#/components/schemas/Pet' 1670default: 1671 description: Unexpected error 1672 content: 1673 application/json: 1674 schema: 1675 $ref: '#/components/schemas/ErrorModel' 1676``` 1677 1678#### <a name="responseObject"></a>Response Object 1679Describes a single response from an API Operation, including design-time, static 1680`links` to operations based on the response. 1681 1682##### Fixed Fields 1683Field Name | Type | Description 1684---|:---:|--- 1685<a name="responseDescription"></a>description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 1686<a name="responseHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. 1687<a name="responseContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* 1688<a name="responseLinks"></a>links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). 1689 1690This object MAY be extended with [Specification Extensions](#specificationExtensions). 1691 1692##### Response Object Examples 1693 1694Response of an array of a complex type: 1695 1696```json 1697{ 1698 "description": "A complex object array response", 1699 "content": { 1700 "application/json": { 1701 "schema": { 1702 "type": "array", 1703 "items": { 1704 "$ref": "#/components/schemas/VeryComplexType" 1705 } 1706 } 1707 } 1708 } 1709} 1710``` 1711 1712```yaml 1713description: A complex object array response 1714content: 1715 application/json: 1716 schema: 1717 type: array 1718 items: 1719 $ref: '#/components/schemas/VeryComplexType' 1720``` 1721 1722Response with a string type: 1723 1724```json 1725{ 1726 "description": "A simple string response", 1727 "content": { 1728 "text/plain": { 1729 "schema": { 1730 "type": "string" 1731 } 1732 } 1733 } 1734 1735} 1736``` 1737 1738```yaml 1739description: A simple string response 1740representations: 1741 text/plain: 1742 schema: 1743 type: string 1744``` 1745 1746Plain text response with headers: 1747 1748```json 1749{ 1750 "description": "A simple string response", 1751 "content": { 1752 "text/plain": { 1753 "schema": { 1754 "type": "string" 1755 } 1756 } 1757 }, 1758 "headers": { 1759 "X-Rate-Limit-Limit": { 1760 "description": "The number of allowed requests in the current period", 1761 "schema": { 1762 "type": "integer" 1763 } 1764 }, 1765 "X-Rate-Limit-Remaining": { 1766 "description": "The number of remaining requests in the current period", 1767 "schema": { 1768 "type": "integer" 1769 } 1770 }, 1771 "X-Rate-Limit-Reset": { 1772 "description": "The number of seconds left in the current period", 1773 "schema": { 1774 "type": "integer" 1775 } 1776 } 1777 } 1778} 1779``` 1780 1781```yaml 1782description: A simple string response 1783content: 1784 text/plain: 1785 schema: 1786 type: string 1787 example: 'whoa!' 1788headers: 1789 X-Rate-Limit-Limit: 1790 description: The number of allowed requests in the current period 1791 schema: 1792 type: integer 1793 X-Rate-Limit-Remaining: 1794 description: The number of remaining requests in the current period 1795 schema: 1796 type: integer 1797 X-Rate-Limit-Reset: 1798 description: The number of seconds left in the current period 1799 schema: 1800 type: integer 1801``` 1802 1803Response with no return value: 1804 1805```json 1806{ 1807 "description": "object created" 1808} 1809``` 1810 1811```yaml 1812description: object created 1813``` 1814 1815#### <a name="callbackObject"></a>Callback Object 1816 1817A map of possible out-of band callbacks related to the parent operation. 1818Each 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. 1819The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. 1820 1821##### Patterned Fields 1822Field Pattern | Type | Description 1823---|:---:|--- 1824<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. 1825 1826This object MAY be extended with [Specification Extensions](#specificationExtensions). 1827 1828##### Key Expression 1829 1830The key that identifies the [Path Item Object](#pathItemObject) is a [runtime expression](#runtimeExpression) that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. 1831A simple example might be `$request.body#/url`. 1832However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. 1833This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. 1834 1835For example, given the following HTTP request: 1836 1837```http 1838POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 1839Host: example.org 1840Content-Type: application/json 1841Content-Length: 187 1842 1843{ 1844 "failedUrl" : "http://clientdomain.com/failed", 1845 "successUrls" : [ 1846 "http://clientdomain.com/fast", 1847 "http://clientdomain.com/medium", 1848 "http://clientdomain.com/slow" 1849 ] 1850} 1851 1852201 Created 1853Location: http://example.org/subscription/1 1854``` 1855 1856The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. 1857 1858Expression | Value 1859---|:--- 1860$url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning 1861$method | POST 1862$request.path.eventType | myevent 1863$request.query.queryUrl | http://clientdomain.com/stillrunning 1864$request.header.content-Type | application/json 1865$request.body#/failedUrl | http://clientdomain.com/stillrunning 1866$request.body#/successUrls/2 | http://clientdomain.com/medium 1867$response.header.Location | http://example.org/subscription/1 1868 1869 1870##### Callback Object Example 1871 1872The following example shows a callback to the URL specified by the `id` and `email` property in the request body. 1873 1874```yaml 1875myWebhook: 1876 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': 1877 post: 1878 requestBody: 1879 description: Callback payload 1880 content: 1881 'application/json': 1882 schema: 1883 $ref: '#/components/schemas/SomePayload' 1884 responses: 1885 '200': 1886 description: webhook successfully processed and no retries will be performed 1887``` 1888 1889 1890#### <a name="exampleObject"></a>Example Object 1891 1892##### Fixed Fields 1893Field Name | Type | Description 1894---|:---:|--- 1895<a name="exampleSummary"></a>summary | `string` | Short description for the example. 1896<a name="exampleDescription"></a>description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 1897<a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. 1898<a name="exampleExternalValue"></a>externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. 1899 1900This object MAY be extended with [Specification Extensions](#specificationExtensions). 1901 1902In all cases, the example value is expected to be compatible with the type schema 1903of its associated value. Tooling implementations MAY choose to 1904validate compatibility automatically, and reject the example value(s) if incompatible. 1905 1906##### Example Object Example 1907 1908```yaml 1909# in a model 1910schemas: 1911 properties: 1912 name: 1913 type: string 1914 examples: 1915 name: 1916 $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example 1917 1918# in a request body: 1919 requestBody: 1920 content: 1921 'application/json': 1922 schema: 1923 $ref: '#/components/schemas/Address' 1924 examples: 1925 foo: 1926 summary: A foo example 1927 value: {"foo": "bar"} 1928 bar: 1929 summary: A bar example 1930 value: {"bar": "baz"} 1931 'application/xml': 1932 examples: 1933 xmlExample: 1934 summary: This is an example in XML 1935 externalValue: 'http://example.org/examples/address-example.xml' 1936 'text/plain': 1937 examples: 1938 textExample: 1939 summary: This is a text example 1940 externalValue: 'http://foo.bar/examples/address-example.txt' 1941 1942 1943# in a parameter 1944 parameters: 1945 - name: 'zipCode' 1946 in: 'query' 1947 schema: 1948 type: 'string' 1949 format: 'zip-code' 1950 examples: 1951 zip-example: 1952 $ref: '#/components/examples/zip-example' 1953 1954# in a response 1955 responses: 1956 '200': 1957 description: your car appointment has been booked 1958 content: 1959 application/json: 1960 schema: 1961 $ref: '#/components/schemas/SuccessResponse' 1962 examples: 1963 confirmation-success: 1964 $ref: '#/components/examples/confirmation-success' 1965``` 1966 1967 1968#### <a name="linkObject"></a>Link Object 1969 1970The `Link object` represents a possible design-time link for a response. 1971The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. 1972 1973Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. 1974 1975For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation. 1976 1977##### Fixed Fields 1978 1979Field Name | Type | Description 1980---|:---:|--- 1981<a name="linkOperationRef"></a>operationRef | `string` | A relative or absolute reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. 1982<a name="linkOperationId"></a>operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. 1983<a name="linkParameters"></a>parameters | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id). 1984<a name="linkRequestBody"></a>requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. 1985<a name="linkDescription"></a>description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 1986<a name="linkServer"></a>server | [Server Object](#serverObject) | A server object to be used by the target operation. 1987 1988This object MAY be extended with [Specification Extensions](#specificationExtensions). 1989 1990A linked operation MUST be identified using either an `operationRef` or `operationId`. 1991In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. 1992Because of the potential for name clashes, the `operationRef` syntax is preferred 1993for specifications with external references. 1994 1995##### Examples 1996 1997Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. 1998 1999```yaml 2000paths: 2001 /users/{id}: 2002 parameters: 2003 - name: id 2004 in: path 2005 required: true 2006 description: the user identifier, as userId 2007 schema: 2008 type: string 2009 get: 2010 responses: 2011 '200': 2012 description: the user being returned 2013 content: 2014 application/json: 2015 schema: 2016 type: object 2017 properties: 2018 uuid: # the unique user id 2019 type: string 2020 format: uuid 2021 links: 2022 address: 2023 # the target link operationId 2024 operationId: getUserAddress 2025 parameters: 2026 # get the `id` field from the request path parameter named `id` 2027 userId: $request.path.id 2028 # the path item of the linked operation 2029 /users/{userid}/address: 2030 parameters: 2031 - name: userid 2032 in: path 2033 required: true 2034 description: the user identifier, as userId 2035 schema: 2036 type: string 2037 # linked operation 2038 get: 2039 operationId: getUserAddress 2040 responses: 2041 '200': 2042 description: the user's address 2043``` 2044 2045When a runtime expression fails to evaluate, no parameter value is passed to the target operation. 2046 2047Values from the response body can be used to drive a linked operation. 2048 2049```yaml 2050links: 2051 address: 2052 operationId: getUserAddressByUUID 2053 parameters: 2054 # get the `id` field from the request path parameter named `id` 2055 userUuid: $response.body#/uuid 2056``` 2057 2058Clients follow all links at their discretion. 2059Neither permissions, nor the capability to make a successful call to that link, is guaranteed 2060solely by the existence of a relationship. 2061 2062 2063##### OperationRef Examples 2064 2065As references to `operationId` MAY NOT be possible (the `operationId` is an optional 2066value), references MAY also be made through a relative `operationRef`: 2067 2068```yaml 2069links: 2070 UserRepositories: 2071 # returns array of '#/components/schemas/repository' 2072 operationRef: '#/paths/~12.0~1repositories~1{username}/get' 2073 parameters: 2074 username: $response.body#/username 2075``` 2076 2077or an absolute `operationRef`: 2078 2079```yaml 2080links: 2081 UserRepositories: 2082 # returns array of '#/components/schemas/repository' 2083 operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' 2084 parameters: 2085 username: $response.body#/username 2086``` 2087 2088Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when 2089using JSON references. 2090 2091 2092##### <a name="runtimeExpression"></a>Runtime Expressions 2093 2094Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. 2095This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). 2096 2097The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax 2098 2099``` 2100 expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) 2101 source = ( header-reference | query-reference | path-reference | body-reference ) 2102 header-reference = "header." token 2103 query-reference = "query." name 2104 path-reference = "path." name 2105 body-reference = "body" ["#" fragment] 2106 fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) 2107 name = *( char ) 2108 char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) 2109 token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) 2110``` 2111 2112The `name` identifier is case-sensitive, whereas `token` is not. 2113 2114The table below provides examples of runtime expressions and examples of their use in a value: 2115 2116##### <a name="runtimeExpressionExamples"></a>Examples 2117 2118Source Location | example expression | notes 2119---|:---|:---| 2120HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. 2121Requested media type | `$request.header.accept` | 2122Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. 2123Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. 2124Request URL | `$url` | 2125Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. 2126Response header | `$response.header.Server` | Single header values only are available 2127 2128Runtime expressions preserve the type of the referenced value. 2129Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. 2130 2131#### <a name="headerObject"></a>Header Object 2132 2133The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 2134 21351. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 21361. `in` MUST NOT be specified, it is implicitly in `header`. 21371. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). 2138 2139##### Header Object Example 2140 2141A simple header of type `integer`: 2142 2143```json 2144{ 2145 "description": "The number of allowed requests in the current period", 2146 "schema": { 2147 "type": "integer" 2148 } 2149} 2150``` 2151 2152```yaml 2153description: The number of allowed requests in the current period 2154schema: 2155 type: integer 2156``` 2157 2158#### <a name="tagObject"></a>Tag Object 2159 2160Adds metadata to a single tag that is used by the [Operation Object](#operationObject). 2161It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. 2162 2163##### Fixed Fields 2164Field Name | Type | Description 2165---|:---:|--- 2166<a name="tagName"></a>name | `string` | **REQUIRED**. The name of the tag. 2167<a name="tagDescription"></a>description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 2168<a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. 2169 2170This object MAY be extended with [Specification Extensions](#specificationExtensions). 2171 2172##### Tag Object Example 2173 2174```json 2175{ 2176 "name": "pet", 2177 "description": "Pets operations" 2178} 2179``` 2180 2181```yaml 2182name: pet 2183description: Pets operations 2184``` 2185 2186#### <a name="examplesObject"></a>Examples Object 2187 2188In an `example`, a JSON Reference MAY be used, with the 2189explicit restriction that examples having a JSON format with object named 2190`$ref` are not allowed. Therefore, that `example`, structurally, can be 2191either a string primitive or an object, similar to `additionalProperties`. 2192 2193In all cases, the payload is expected to be compatible with the type schema 2194for the associated value. Tooling implementations MAY choose to 2195validate compatibility automatically, and reject the example value(s) if they 2196are incompatible. 2197 2198```yaml 2199# in a model 2200schemas: 2201 properties: 2202 name: 2203 type: string 2204 example: 2205 $ref: http://foo.bar#/examples/name-example 2206 2207# in a request body, note the plural `examples` 2208 requestBody: 2209 content: 2210 'application/json': 2211 schema: 2212 $ref: '#/components/schemas/Address' 2213 examples: 2214 foo: 2215 value: {"foo": "bar"} 2216 bar: 2217 value: {"bar": "baz"} 2218 'application/xml': 2219 examples: 2220 xml: 2221 externalValue: 'http://foo.bar/examples/address-example.xml' 2222 'text/plain': 2223 examples: 2224 text: 2225 externalValue: 'http://foo.bar/examples/address-example.txt' 2226 2227# in a parameter 2228 parameters: 2229 - name: 'zipCode' 2230 in: 'query' 2231 schema: 2232 type: 'string' 2233 format: 'zip-code' 2234 example: 2235 $ref: 'http://foo.bar#/examples/zip-example' 2236 2237# in a response, note the singular `example`: 2238 responses: 2239 '200': 2240 description: your car appointment has been booked 2241 content: 2242 application/json: 2243 schema: 2244 $ref: '#/components/schemas/SuccessResponse' 2245 example: 2246 $ref: http://foo.bar#/examples/address-example.json 2247``` 2248 2249#### <a name="referenceObject"></a>Reference Object 2250 2251A simple object to allow referencing other components in the specification, internally and externally. 2252 2253The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. 2254 2255For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. 2256 2257##### Fixed Fields 2258Field Name | Type | Description 2259---|:---:|--- 2260<a name="referenceRef"></a>$ref | `string` | **REQUIRED**. The reference string. 2261 2262This object cannot be extended with additional properties and any properties added SHALL be ignored. 2263 2264##### Reference Object Example 2265 2266```json 2267{ 2268 "$ref": "#/components/schemas/Pet" 2269} 2270``` 2271 2272```yaml 2273$ref: '#/components/schemas/Pet' 2274``` 2275 2276##### Relative Schema Document Example 2277```json 2278{ 2279 "$ref": "Pet.json" 2280} 2281``` 2282 2283```yaml 2284$ref: Pet.yaml 2285``` 2286 2287##### Relative Documents With Embedded Schema Example 2288```json 2289{ 2290 "$ref": "definitions.json#/Pet" 2291} 2292``` 2293 2294```yaml 2295$ref: definitions.yaml#/Pet 2296``` 2297 2298#### <a name="schemaObject"></a>Schema Object 2299 2300The Schema Object allows the definition of input and output data types. 2301These types can be objects, but also primitives and arrays. 2302This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/). 2303 2304For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00). 2305Unless stated otherwise, the property definitions follow the JSON Schema. 2306 2307##### Properties 2308 2309The following properties are taken directly from the JSON Schema definition and follow the same specifications: 2310 2311- title 2312- multipleOf 2313- maximum 2314- exclusiveMaximum 2315- minimum 2316- exclusiveMinimum 2317- maxLength 2318- minLength 2319- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-7.8.5) dialect) 2320- maxItems 2321- minItems 2322- uniqueItems 2323- maxProperties 2324- minProperties 2325- required 2326- enum 2327 2328The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. 2329- type - Value MUST be a string. Multiple types via an array are not supported. 2330- allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. 2331- oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. 2332- anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. 2333- not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. 2334- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`. 2335- properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). 2336- additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. 2337- description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 2338- format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats. 2339- 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`. 2340 2341Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions instead of defining them inline. 2342 2343Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. 2344 2345Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: 2346 2347##### Fixed Fields 2348Field Name | Type | Description 2349---|:---:|--- 2350<a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. 2351<a name="schemaDiscriminator"></a>discriminator | [Discriminator Object](#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](#schemaComposition) for more details. 2352<a name="schemaReadOnly"></a>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`. 2353<a name="schemaWriteOnly"></a>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`. 2354<a name="schemaXml"></a>xml | [XML Object](#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. 2355<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 2356<a name="schemaExample"></a>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. 2357<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. 2358 2359This object MAY be extended with [Specification Extensions](#specificationExtensions). 2360 2361###### <a name="schemaComposition"></a>Composition and Inheritance (Polymorphism) 2362 2363The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. 2364`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. 2365 2366While composition offers model extensibility, it does not imply a hierarchy between the models. 2367To support polymorphism, the OpenAPI Specification adds the `discriminator` field. 2368When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. 2369As such, the `discriminator` field MUST be a required field. 2370There are are two ways to define the value of a discriminator for an inheriting instance. 2371- Use the schema name. 2372- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. 2373As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. 2374 2375###### XML Modeling 2376 2377The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. 2378The [XML Object](#xmlObject) contains additional information about the available options. 2379 2380##### Schema Object Examples 2381 2382###### Primitive Sample 2383 2384```json 2385{ 2386 "type": "string", 2387 "format": "email" 2388} 2389``` 2390 2391```yaml 2392type: string 2393format: email 2394``` 2395 2396###### Simple Model 2397 2398```json 2399{ 2400 "type": "object", 2401 "required": [ 2402 "name" 2403 ], 2404 "properties": { 2405 "name": { 2406 "type": "string" 2407 }, 2408 "address": { 2409 "$ref": "#/components/schemas/Address" 2410 }, 2411 "age": { 2412 "type": "integer", 2413 "format": "int32", 2414 "minimum": 0 2415 } 2416 } 2417} 2418``` 2419 2420```yaml 2421type: object 2422required: 2423- name 2424properties: 2425 name: 2426 type: string 2427 address: 2428 $ref: '#/components/schemas/Address' 2429 age: 2430 type: integer 2431 format: int32 2432 minimum: 0 2433``` 2434 2435###### Model with Map/Dictionary Properties 2436 2437For a simple string to string mapping: 2438 2439```json 2440{ 2441 "type": "object", 2442 "additionalProperties": { 2443 "type": "string" 2444 } 2445} 2446``` 2447 2448```yaml 2449type: object 2450additionalProperties: 2451 type: string 2452``` 2453 2454For a string to model mapping: 2455 2456```json 2457{ 2458 "type": "object", 2459 "additionalProperties": { 2460 "$ref": "#/components/schemas/ComplexModel" 2461 } 2462} 2463``` 2464 2465```yaml 2466type: object 2467additionalProperties: 2468 $ref: '#/components/schemas/ComplexModel' 2469``` 2470 2471###### Model with Example 2472 2473```json 2474{ 2475 "type": "object", 2476 "properties": { 2477 "id": { 2478 "type": "integer", 2479 "format": "int64" 2480 }, 2481 "name": { 2482 "type": "string" 2483 } 2484 }, 2485 "required": [ 2486 "name" 2487 ], 2488 "example": { 2489 "name": "Puma", 2490 "id": 1 2491 } 2492} 2493``` 2494 2495```yaml 2496type: object 2497properties: 2498 id: 2499 type: integer 2500 format: int64 2501 name: 2502 type: string 2503required: 2504- name 2505example: 2506 name: Puma 2507 id: 1 2508``` 2509 2510###### Models with Composition 2511 2512```json 2513{ 2514 "components": { 2515 "schemas": { 2516 "ErrorModel": { 2517 "type": "object", 2518 "required": [ 2519 "message", 2520 "code" 2521 ], 2522 "properties": { 2523 "message": { 2524 "type": "string" 2525 }, 2526 "code": { 2527 "type": "integer", 2528 "minimum": 100, 2529 "maximum": 600 2530 } 2531 } 2532 }, 2533 "ExtendedErrorModel": { 2534 "allOf": [ 2535 { 2536 "$ref": "#/components/schemas/ErrorModel" 2537 }, 2538 { 2539 "type": "object", 2540 "required": [ 2541 "rootCause" 2542 ], 2543 "properties": { 2544 "rootCause": { 2545 "type": "string" 2546 } 2547 } 2548 } 2549 ] 2550 } 2551 } 2552 } 2553} 2554``` 2555 2556```yaml 2557components: 2558 schemas: 2559 ErrorModel: 2560 type: object 2561 required: 2562 - message 2563 - code 2564 properties: 2565 message: 2566 type: string 2567 code: 2568 type: integer 2569 minimum: 100 2570 maximum: 600 2571 ExtendedErrorModel: 2572 allOf: 2573 - $ref: '#/components/schemas/ErrorModel' 2574 - type: object 2575 required: 2576 - rootCause 2577 properties: 2578 rootCause: 2579 type: string 2580``` 2581 2582###### Models with Polymorphism Support 2583 2584```json 2585{ 2586 "components": { 2587 "schemas": { 2588 "Pet": { 2589 "type": "object", 2590 "discriminator": { 2591 "propertyName": "petType" 2592 }, 2593 "properties": { 2594 "name": { 2595 "type": "string" 2596 }, 2597 "petType": { 2598 "type": "string" 2599 } 2600 }, 2601 "required": [ 2602 "name", 2603 "petType" 2604 ] 2605 }, 2606 "Cat": { 2607 "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", 2608 "allOf": [ 2609 { 2610 "$ref": "#/components/schemas/Pet" 2611 }, 2612 { 2613 "type": "object", 2614 "properties": { 2615 "huntingSkill": { 2616 "type": "string", 2617 "description": "The measured skill for hunting", 2618 "default": "lazy", 2619 "enum": [ 2620 "clueless", 2621 "lazy", 2622 "adventurous", 2623 "aggressive" 2624 ] 2625 } 2626 }, 2627 "required": [ 2628 "huntingSkill" 2629 ] 2630 } 2631 ] 2632 }, 2633 "Dog": { 2634 "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", 2635 "allOf": [ 2636 { 2637 "$ref": "#/components/schemas/Pet" 2638 }, 2639 { 2640 "type": "object", 2641 "properties": { 2642 "packSize": { 2643 "type": "integer", 2644 "format": "int32", 2645 "description": "the size of the pack the dog is from", 2646 "default": 0, 2647 "minimum": 0 2648 } 2649 }, 2650 "required": [ 2651 "packSize" 2652 ] 2653 } 2654 ] 2655 } 2656 } 2657 } 2658} 2659``` 2660 2661```yaml 2662components: 2663 schemas: 2664 Pet: 2665 type: object 2666 discriminator: 2667 propertyName: petType 2668 properties: 2669 name: 2670 type: string 2671 petType: 2672 type: string 2673 required: 2674 - name 2675 - petType 2676 Cat: ## "Cat" will be used as the discriminator value 2677 description: A representation of a cat 2678 allOf: 2679 - $ref: '#/components/schemas/Pet' 2680 - type: object 2681 properties: 2682 huntingSkill: 2683 type: string 2684 description: The measured skill for hunting 2685 enum: 2686 - clueless 2687 - lazy 2688 - adventurous 2689 - aggressive 2690 required: 2691 - huntingSkill 2692 Dog: ## "Dog" will be used as the discriminator value 2693 description: A representation of a dog 2694 allOf: 2695 - $ref: '#/components/schemas/Pet' 2696 - type: object 2697 properties: 2698 packSize: 2699 type: integer 2700 format: int32 2701 description: the size of the pack the dog is from 2702 default: 0 2703 minimum: 0 2704 required: 2705 - packSize 2706``` 2707 2708#### <a name="discriminatorObject"></a>Discriminator Object 2709 2710When 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 specification of an alternative schema based on the value associated with it. 2711 2712When using the discriminator, _inline_ schemas will not be considered. 2713 2714##### Fixed Fields 2715Field Name | Type | Description 2716---|:---:|--- 2717<a name="propertyName"></a>propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. 2718<a name="discriminatorMapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. 2719 2720The discriminator attribute is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. 2721 2722In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: 2723 2724``` 2725MyResponseType: 2726 oneOf: 2727 - $ref: '#/components/schemas/Cat' 2728 - $ref: '#/components/schemas/Dog' 2729 - $ref: '#/components/schemas/Lizard' 2730``` 2731 2732which 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: 2733 2734 2735``` 2736MyResponseType: 2737 oneOf: 2738 - $ref: '#/components/schemas/Cat' 2739 - $ref: '#/components/schemas/Dog' 2740 - $ref: '#/components/schemas/Lizard' 2741 discriminator: 2742 propertyName: pet_type 2743``` 2744 2745The expectation now is that a property with name `pet_type` _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: 2746 2747``` 2748{ 2749 "id": 12345, 2750 "pet_type": "Cat" 2751} 2752``` 2753 2754Will indicate that the `Cat` schema be used in conjunction with this payload. 2755 2756In 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: 2757 2758``` 2759MyResponseType: 2760 oneOf: 2761 - $ref: '#/components/schemas/Cat' 2762 - $ref: '#/components/schemas/Dog' 2763 - $ref: '#/components/schemas/Lizard' 2764 - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' 2765 discriminator: 2766 propertyName: pet_type 2767 mapping: 2768 dog: '#/components/schemas/Dog' 2769 monster: 'https://gigantic-server.com/schemas/Monster/schema.json' 2770``` 2771 2772Here 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. 2773 2774When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. 2775 2776In 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. 2777 2778For example: 2779 2780``` 2781components: 2782 schemas: 2783 Pet: 2784 type: object 2785 required: 2786 - pet_type 2787 properties: 2788 pet_type: 2789 type: string 2790 discriminator: 2791 propertyName: pet_type 2792 mapping: 2793 cachorro: Dog 2794 Cat: 2795 allOf: 2796 - $ref: '#/components/schemas/Pet' 2797 - type: object 2798 # all other properties specific to a `Cat` 2799 properties: 2800 name: 2801 type: string 2802 Dog: 2803 allOf: 2804 - $ref: '#/components/schemas/Pet' 2805 - type: object 2806 # all other properties specific to a `Dog` 2807 properties: 2808 bark: 2809 type: string 2810 Lizard: 2811 allOf: 2812 - $ref: '#/components/schemas/Pet' 2813 - type: object 2814 # all other properties specific to a `Lizard` 2815 properties: 2816 lovesRocks: 2817 type: boolean 2818``` 2819 2820a payload like this: 2821 2822``` 2823{ 2824 "pet_type": "Cat", 2825 "name": "misty" 2826} 2827``` 2828 2829will indicate that the `Cat` schema be used. Likewise this schema: 2830 2831``` 2832{ 2833 "pet_type": "cachorro", 2834 "bark": "soft" 2835} 2836``` 2837 2838will map to `Dog` because of the definition in the `mappings` element. 2839 2840 2841#### <a name="xmlObject"></a>XML Object 2842 2843A metadata object that allows for more fine-tuned XML model definitions. 2844 2845When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. 2846See examples for expected behavior. 2847 2848##### Fixed Fields 2849Field Name | Type | Description 2850---|:---:|--- 2851<a name="xmlName"></a>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. 2852<a name="xmlNamespace"></a>namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. 2853<a name="xmlPrefix"></a>prefix | `string` | The prefix to be used for the [name](#xmlName). 2854<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. 2855<a name="xmlWrapped"></a>wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `<books><book/><book/></books>`) or unwrapped (`<book/><book/>`). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). 2856 2857This object MAY be extended with [Specification Extensions](#specificationExtensions). 2858 2859##### XML Object Examples 2860 2861The examples of the XML object definitions are included inside a property definition of a [Schema Object](#schemaObject) with a sample of the XML representation of it. 2862 2863###### No XML Element 2864 2865Basic string property: 2866 2867```json 2868{ 2869 "animals": { 2870 "type": "string" 2871 } 2872} 2873``` 2874 2875```yaml 2876animals: 2877 type: string 2878``` 2879 2880```xml 2881<animals>...</animals> 2882``` 2883 2884Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): 2885 2886```json 2887{ 2888 "animals": { 2889 "type": "array", 2890 "items": { 2891 "type": "string" 2892 } 2893 } 2894} 2895``` 2896 2897```yaml 2898animals: 2899 type: array 2900 items: 2901 type: string 2902``` 2903 2904```xml 2905<animals>...</animals> 2906<animals>...</animals> 2907<animals>...</animals> 2908``` 2909 2910###### XML Name Replacement 2911 2912```json 2913{ 2914 "animals": { 2915 "type": "string", 2916 "xml": { 2917 "name": "animal" 2918 } 2919 } 2920} 2921``` 2922 2923```yaml 2924animals: 2925 type: string 2926 xml: 2927 name: animal 2928``` 2929 2930```xml 2931<animal>...</animal> 2932``` 2933 2934 2935###### XML Attribute, Prefix and Namespace 2936 2937In this example, a full model definition is shown. 2938 2939```json 2940{ 2941 "Person": { 2942 "type": "object", 2943 "properties": { 2944 "id": { 2945 "type": "integer", 2946 "format": "int32", 2947 "xml": { 2948 "attribute": true 2949 } 2950 }, 2951 "name": { 2952 "type": "string", 2953 "xml": { 2954 "namespace": "http://example.com/schema/sample", 2955 "prefix": "sample" 2956 } 2957 } 2958 } 2959 } 2960} 2961``` 2962 2963```yaml 2964Person: 2965 type: object 2966 properties: 2967 id: 2968 type: integer 2969 format: int32 2970 xml: 2971 attribute: true 2972 name: 2973 type: string 2974 xml: 2975 namespace: http://example.com/schema/sample 2976 prefix: sample 2977``` 2978 2979```xml 2980<Person id="123"> 2981 <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name> 2982</Person> 2983``` 2984 2985###### XML Arrays 2986 2987Changing the element names: 2988 2989```json 2990{ 2991 "animals": { 2992 "type": "array", 2993 "items": { 2994 "type": "string", 2995 "xml": { 2996 "name": "animal" 2997 } 2998 } 2999 } 3000} 3001``` 3002 3003```yaml 3004animals: 3005 type: array 3006 items: 3007 type: string 3008 xml: 3009 name: animal 3010``` 3011 3012```xml 3013<animal>value</animal> 3014<animal>value</animal> 3015``` 3016 3017The external `name` property has no effect on the XML: 3018 3019```json 3020{ 3021 "animals": { 3022 "type": "array", 3023 "items": { 3024 "type": "string", 3025 "xml": { 3026 "name": "animal" 3027 } 3028 }, 3029 "xml": { 3030 "name": "aliens" 3031 } 3032 } 3033} 3034``` 3035 3036```yaml 3037animals: 3038 type: array 3039 items: 3040 type: string 3041 xml: 3042 name: animal 3043 xml: 3044 name: aliens 3045``` 3046 3047```xml 3048<animal>value</animal> 3049<animal>value</animal> 3050``` 3051 3052Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: 3053 3054```json 3055{ 3056 "animals": { 3057 "type": "array", 3058 "items": { 3059 "type": "string" 3060 }, 3061 "xml": { 3062 "wrapped": true 3063 } 3064 } 3065} 3066``` 3067 3068```yaml 3069animals: 3070 type: array 3071 items: 3072 type: string 3073 xml: 3074 wrapped: true 3075``` 3076 3077```xml 3078<animals> 3079 <animals>value</animals> 3080 <animals>value</animals> 3081</animals> 3082``` 3083 3084To overcome the naming problem in the example above, the following definition can be used: 3085 3086```json 3087{ 3088 "animals": { 3089 "type": "array", 3090 "items": { 3091 "type": "string", 3092 "xml": { 3093 "name": "animal" 3094 } 3095 }, 3096 "xml": { 3097 "wrapped": true 3098 } 3099 } 3100} 3101``` 3102 3103```yaml 3104animals: 3105 type: array 3106 items: 3107 type: string 3108 xml: 3109 name: animal 3110 xml: 3111 wrapped: true 3112``` 3113 3114```xml 3115<animals> 3116 <animal>value</animal> 3117 <animal>value</animal> 3118</animals> 3119``` 3120 3121Affecting both internal and external names: 3122 3123```json 3124{ 3125 "animals": { 3126 "type": "array", 3127 "items": { 3128 "type": "string", 3129 "xml": { 3130 "name": "animal" 3131 } 3132 }, 3133 "xml": { 3134 "name": "aliens", 3135 "wrapped": true 3136 } 3137 } 3138} 3139``` 3140 3141```yaml 3142animals: 3143 type: array 3144 items: 3145 type: string 3146 xml: 3147 name: animal 3148 xml: 3149 name: aliens 3150 wrapped: true 3151``` 3152 3153```xml 3154<aliens> 3155 <animal>value</animal> 3156 <animal>value</animal> 3157</aliens> 3158``` 3159 3160If we change the external element but not the internal ones: 3161 3162```json 3163{ 3164 "animals": { 3165 "type": "array", 3166 "items": { 3167 "type": "string" 3168 }, 3169 "xml": { 3170 "name": "aliens", 3171 "wrapped": true 3172 } 3173 } 3174} 3175``` 3176 3177```yaml 3178animals: 3179 type: array 3180 items: 3181 type: string 3182 xml: 3183 name: aliens 3184 wrapped: true 3185``` 3186 3187```xml 3188<aliens> 3189 <aliens>value</aliens> 3190 <aliens>value</aliens> 3191</aliens> 3192``` 3193 3194#### <a name="securitySchemeObject"></a>Security Scheme Object 3195 3196Defines a security scheme that can be used by the operations. 3197Supported 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). 3198 3199##### Fixed Fields 3200Field Name | Type | Applies To | Description 3201---|:---:|---|--- 3202<a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. 3203<a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 3204<a name="securitySchemeName"></a>name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. 3205<a name="securitySchemeIn"></a>in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. 3206<a name="securitySchemeScheme"></a>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). 3207<a name="securitySchemeBearerFormat"></a>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. 3208<a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. 3209<a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. 3210 3211This object MAY be extended with [Specification Extensions](#specificationExtensions). 3212 3213##### Security Scheme Object Example 3214 3215###### Basic Authentication Sample 3216 3217```json 3218{ 3219 "type": "http", 3220 "scheme": "basic" 3221} 3222``` 3223 3224```yaml 3225type: http 3226scheme: basic 3227``` 3228 3229###### API Key Sample 3230 3231```json 3232{ 3233 "type": "apiKey", 3234 "name": "api_key", 3235 "in": "header" 3236} 3237``` 3238 3239```yaml 3240type: apiKey 3241name: api_key 3242in: header 3243``` 3244 3245###### JWT Bearer Sample 3246 3247```json 3248{ 3249 "type": "http", 3250 "scheme": "bearer", 3251 "bearerFormat": "JWT", 3252} 3253``` 3254 3255```yaml 3256type: http 3257scheme: bearer 3258bearerFormat: JWT 3259``` 3260 3261###### Implicit OAuth2 Sample 3262 3263```json 3264{ 3265 "type": "oauth2", 3266 "flows": { 3267 "implicit": { 3268 "authorizationUrl": "https://example.com/api/oauth/dialog", 3269 "scopes": { 3270 "write:pets": "modify pets in your account", 3271 "read:pets": "read your pets" 3272 } 3273 } 3274 } 3275} 3276``` 3277 3278```yaml 3279type: oauth2 3280flows: 3281 implicit: 3282 authorizationUrl: https://example.com/api/oauth/dialog 3283 scopes: 3284 write:pets: modify pets in your account 3285 read:pets: read your pets 3286``` 3287 3288#### <a name="oauthFlowsObject"></a>OAuth Flows Object 3289 3290Allows configuration of the supported OAuth Flows. 3291 3292##### Fixed Fields 3293Field Name | Type | Description 3294---|:---:|--- 3295<a name="oauthFlowsImplicit"></a>implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow 3296<a name="oauthFlowsPassword"></a>password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow 3297<a name="oauthFlowsClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. 3298<a name="oauthFlowsAuthorizationCode"></a>authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. 3299 3300This object MAY be extended with [Specification Extensions](#specificationExtensions). 3301 3302#### <a name="oauthFlowObject"></a>OAuth Flow Object 3303 3304Configuration details for a supported OAuth Flow 3305 3306##### Fixed Fields 3307Field Name | Type | Applies To | Description 3308---|:---:|---|--- 3309<a name="oauthFlowAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. 3310<a name="oauthFlowTokenUrl"></a>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. 3311<a name="oauthFlowRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. 3312<a name="oauthFlowScopes"></a>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. 3313 3314This object MAY be extended with [Specification Extensions](#specificationExtensions). 3315 3316##### OAuth Flow Object Examples 3317 3318```JSON 3319{ 3320 "type": "oauth2", 3321 "flows": { 3322 "implicit": { 3323 "authorizationUrl": "https://example.com/api/oauth/dialog", 3324 "scopes": { 3325 "write:pets": "modify pets in your account", 3326 "read:pets": "read your pets" 3327 } 3328 }, 3329 "authorizationCode": { 3330 "authorizationUrl": "https://example.com/api/oauth/dialog", 3331 "tokenUrl": "https://example.com/api/oauth/token", 3332 "scopes": { 3333 "write:pets": "modify pets in your account", 3334 "read:pets": "read your pets" 3335 } 3336 } 3337 } 3338} 3339``` 3340 3341```YAML 3342type: oauth2 3343flows: 3344 implicit: 3345 authorizationUrl: https://example.com/api/oauth/dialog 3346 scopes: 3347 write:pets: modify pets in your account 3348 read:pets: read your pets 3349 authorizationCode: 3350 authorizationUrl: https://example.com/api/oauth/dialog 3351 tokenUrl: https://example.com/api/oauth/token 3352 scopes: 3353 write:pets: modify pets in your account 3354 read:pets: read your pets 3355``` 3356 3357 3358#### <a name="securityRequirementObject"></a>Security Requirement Object 3359 3360Lists the required security schemes to execute this operation. 3361The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). 3362 3363Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. 3364This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. 3365 3366When 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. 3367 3368##### Patterned Fields 3369 3370Field Pattern | Type | Description 3371---|:---:|--- 3372<a name="securityRequirementsName"></a>{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. 3373 3374##### Security Requirement Object Examples 3375 3376###### Non-OAuth2 Security Requirement 3377 3378```json 3379{ 3380 "api_key": [] 3381} 3382``` 3383 3384```yaml 3385api_key: [] 3386``` 3387 3388###### OAuth2 Security Requirement 3389 3390```json 3391{ 3392 "petstore_auth": [ 3393 "write:pets", 3394 "read:pets" 3395 ] 3396} 3397``` 3398 3399```yaml 3400petstore_auth: 3401- write:pets 3402- read:pets 3403``` 3404 3405### <a name="specificationExtensions"></a>Specification Extensions 3406 3407While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. 3408 3409The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. 3410 3411Field Pattern | Type | Description 3412---|:---:|--- 3413<a name="infoExtensions"></a>^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. 3414 3415The 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). 3416 3417### <a name="securityFiltering"></a>Security Filtering 3418 3419Some 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. 3420 3421The reasoning is to allow an additional layer of access control over the documentation. 3422While 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. 3423 3424Two examples of this: 3425 34261. 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. 34272. 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. 3428 3429## <a name="revisionHistory"></a>Appendix A: Revision History 3430 3431Version | Date | Notes 3432--- | --- | --- 34333.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 34343.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 34353.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 34363.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 34372.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative 34382.0 | 2014-09-08 | Release of Swagger 2.0 34391.2 | 2014-03-14 | Initial release of the formal document. 34401.1 | 2012-08-22 | Release of Swagger 1.1 34411.0 | 2011-08-10 | First release of the Swagger Specification 3442