pax_global_header00006660000000000000000000000064140130165250014507gustar00rootroot0000000000000052 comment=42a9e3d4eddade52363a5c4fac852e80681c2fe5 OpenAPI-Specification-3.1.0/000077500000000000000000000000001401301652500155215ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/.github/000077500000000000000000000000001401301652500170615ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/.github/workflows/000077500000000000000000000000001401301652500211165ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/.github/workflows/convert-examples-to-json.yaml000066400000000000000000000025751401301652500266760ustar00rootroot00000000000000name: convert-examples-to-json # author: @MikeRalphson / @cebe # issue: https://github.com/OAI/OpenAPI-Specification/issues/1385 # # This workflow updates the *.json files in the examples/v3.x directories, # when the corresponding *.yaml files change. # JSON example files are automatically generated from the YAML example files. # Only the YAML files should be adjusted manually. # # run this on push to master on: push: branches: - master jobs: yaml2json: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 # checkout repo content - name: Install dependencies run: npm i - name: convert YAML examples to JSON run: find examples/v3* -type f -name "*.yaml" | xargs node scripts/yaml2json/yaml2json.js - name: git diff run: | git add examples/**/*.json git --no-pager -c color.diff=always diff --staged - name: Create Pull Request uses: peter-evans/create-pull-request@v1 with: token: ${{ secrets.GITHUB_TOKEN }} branch-suffix: none branch: update-json-examples title: Update JSON example files commit-message: Update JSON example files body: | This pull request is automatically triggered by GitHub action `convert-examples-to-json`. The examples/v3.* YAML files have changed, so the JSON files are automatically being recreated. OpenAPI-Specification-3.1.0/.github/workflows/validate-markdown.yaml000066400000000000000000000012521401301652500254130ustar00rootroot00000000000000name: validate-markdown # Author: @MikeRalphson # Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130 # # This workflow validates files in the versions directory matching 3.*.md # Versions before 3.0 are not validated, as they contain linking errors # where it is not currently planned to go back and fix them # # run this on push to any branch and creation of pull-requests on: [push, pull_request] jobs: mdv: runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 # checkout repo content - uses: actions/setup-node@v1 # setup Node.js with: node-version: '12.x' - name: Validate markdown run: npx mdv versions/3.*.md OpenAPI-Specification-3.1.0/.gitignore000066400000000000000000000001451401301652500175110ustar00rootroot00000000000000.idea *.iml *.ipr *.iws target atlassian-ide-plugin.xml node_modules/ package-lock.json Gemfile.lock OpenAPI-Specification-3.1.0/CODE_OF_CONDUCT.md000066400000000000000000000113531401301652500203230ustar00rootroot00000000000000Code of Conduct =============== OpenAPI Initiative Code of Conduct *The Linux Foundation* *Effective November 24, 2020* The OpenAPI Initiative (OAI) is an open source Linux Foundation project and home of the OpenAPI Specification (OAS) released under the Apache 2.0 license. As contributors, maintainers, and participants in this project, we want to foster an open and welcoming environment. We pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. Our Standards ------------- Examples of behaviors that contribute to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members - Assuming the best intent from others Examples of unacceptable behavior by participants include: - The use of sexualized language or imagery and unwelcome sexual attention or advances - Making unsolicited, insulting or derogatory comments, including personal (i.e., ad hominem) or political attacks to create conflict (e.g., trolling) - Public or private harassment - Publishing others' private information, such as a physical or electronic address, without explicit permission (e.g., doxxing) - Threatening, offensive, harmful comments, or behavior - Other conduct which could reasonably be considered inappropriate in a professional setting Our Responsibilities -------------------- The Code of Conduct Committee is responsible for clarifying the standards of acceptable behavior and is expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Scope ----- This Code of Conduct applies to OAI project spaces, as well as interactions in public spaces. Project spaces include, but are not limited to, official OAI code repositories, Slack, mailing lists, meetings, and events. Public spaces may include venues where an individual is representing the project or its community. Examples of this include a community member's email communication, forum posts, social media activity, or acting as a representative at an online or offline event. In addition, violations of this code of conduct outside of these spaces may affect a person's ability to participate in them. Enforcement ----------- To report instances of abuse, harassment, or otherwise unacceptable behavior, contact [conduct\@openapis.org](mailto:conduct@openapis.org). **We are committed to maintaining the confidentiality of anyone reporting an incident**. The Code of Conduct Committee will review and investigate all complaints, responding as deemed necessary and appropriate to the circumstances. For incidents relating to offline events, we aim to respond to reports within 24 hours, and for incidents relating to online activities, we aim to respond to reports within 7 days. The Code of Conduct Committee has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or take other appropriate action as deemed necessary for behaviors contrary to the standards listed above. In the case of offline or in-person events, if a participant engages in behavior that is not aligned to this Code of Conduct, the committee may take action, such as warning the offender, banning the offender from various online spaces (temporary or permanent), removing the offender from an event with no refund, or other options deemed appropriate. Further details of specific enforcement policies are currently being drafted. When these details are completed we will post updates to our website for transparency. Project maintainers who do not report possible incidents or follow responses in good faith may face temporary or permanent repercussions as determined by the Code of Conduct Committee. ### Events Some OpenAPI events are governed by the [Linux Foundation Code of Conduct](https://events.linuxfoundation.org/about/code-of-conduct/) (E.g. API Specifications Conference) and will be listed on the event page. The OAI Code of Conduct is designed to be compatible with the above policy and also includes more details on responding to incidents. ### Attribution This code of conduct is adapted from the [Contributor Covenant, version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct) and the [PyCon 2019 Code of Conduct](https://us.pycon.org/2019/about/code-of-conduct/). OpenAPI-Specification-3.1.0/CONTRIBUTORS.md000066400000000000000000000010071401301652500177760ustar00rootroot00000000000000* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) * Jason Harmon [@jharmn](https://github.com/jharmn) * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) * Kris Hahn [@KrisHahn](https://github.com/krishahn) * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) * Mike Ralphson [@MikeRalphson](https://github.com/mikeralphson) * Rob Dolin [@RobDolinMS](https://github.com/robdolinms) * Ron Ratovsky [@webron](https://github.com/webron) * Tony Tam [@fehguy](https://github.com/fehguy) OpenAPI-Specification-3.1.0/DEVELOPMENT.md000066400000000000000000000224741401301652500176360ustar00rootroot00000000000000## Development Guidelines This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The OpenAPI Technical Steering Committee (TSC) will initially follow these processes when merging changes from external contributors or from the TSC itself. This guideline document will be adjusted as practicality dictates. ## OAI Specification Driving factors The OpenAPI Specification should be use-case driven. We can specify support for hypothetical use cases as we see fit, but specifications should be backed by realistic scenarios. ## Specification Change Criteria The specification *will evolve over time*. Changes may be made when any of the following criteria are met: * Clarity. The current "way" something is done doesn't make sense, is complicated, or not clear. * Consistency. A portion of the specification is not consistent with the rest, or with the industry standard terminology. * Necessary functionality. We are missing functionality because of a certain design of the specification. * Forward-looking designs. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. * Impact. A change will provide impact on a large number of use cases. We should not be forced to accommodate every use case. We should strive to make the *common* and *important* use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. ## Specification Change Process For each change in the specification we should *always* consider the following: * Migration. Is this a construct that has a path from the existing 2.0 specification? If so, how complicated is it to migrate to the proposed change? * Tooling. Strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. * Visualization. Can the specification change be graphically visualized somehow in a UI or other interface? Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @webron" however at least one formal GitHub-based flow approval must be given. After voting criteria is met, any committer can merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. ## Tracking Process * GitHub is the medium of record for all spec designs, use cases, and so on. * As with 2.0, the **human readable** document is the source of truth. If using a JSON Schema again to document the spec, it is secondary to the human documentation. The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example). * At any given time, there would be *at most* 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0: * master - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. * v3.0.1-dev - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. * v3.1.0 - The next MINOR version. * v4.0.0 - The next MAJOR version. * The master branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on master. * Examples of how something is described *currently* vs. the proposed solution should accompany any change proposal. * New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch. * Use labels for the workflow of specification changes. Examples of labels are proposed, housekeeping, migration-review, tooling-, needs documentation, review (candidate for upcoming TSC mtg), rejected, and needs approval. These labels must be assigned by project committers. Style is lowercase with dashes in place of spaces. * An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. * A PR will be used to describe the *proposed* solution and linked to the original issue. * Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. * When the work branch is ready and approved, the branch will be merged to master. ## Release Process A release requires a vote on the release notes by TSC members within the voting period. Major or minor release voting periods will be announced by the Liaison in the Slack channel and noted on the calendar at least 6 days in advance. During this time, TSC members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases happen at the first TSC meeting of a calendar month. The Liaison is responsible for coordinating the actual merge to Master with marketing support, if any. * Patch-level releases require majority approval by TSC members. (Max voting period 3 days) * Minor: requires approval by 66% of TSC members. (Max voting period 7 days) * Major: requires approval by 66% of TSC members. (Max voting period 14 days) ## Draft Features Where suitable, features will be introduced as draft but OAI approved extensions. By introducing new features this way we enable new features to be designed, documented and then implemented by tools that are interested in the feature, without putting the burden of implementation on all tooling. If the feature is successfully implemented and there is demonstrable value added by the feature, it will become a candidate for inclusion in a future release of the specification, at which point all tools will be expected to support the feature. Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted. This ensures no existing tooling will affected by the introduction of the draft feature. If the feature is deemed appropriate for inclusion in the OAS, the `x-oas-draft-` prefix will be removed. Tooling that supports draft features should plan for the future removal of the prefix. When tooling adds support for a later version of OAS that includes the final implementation of the feature, it MUST not support the use of the draft prefix for that feature. Draft features will only be promoted into minor or major releases of the specification and therefore will be transparent to OpenAPI description writers and tooling providers who choose not to use the feature while in its draft state. Draft features will be documented as GitHub issues and labeled with the `draft-feature` label and will be initially labelled as `draft:proposal`. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled `draft:pilot`. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the extension name itself may be versioned with a version suffix. e.g. `-v2` When a draft feature becomes part of a future update to the specification any version suffix will be removed. Draft features that are deemed not appropriate for inclusion MUST be marked with the `draft:abandoned` label. Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the `draft:graduated` label. Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in an extension. However, where a new feature can be introduced in this way, it should be. ## Transparency The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project. ## Participation While governance of the specification is the role of the TSC, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. ## Community Roles While these developer community roles are informal, there are many ways to get involved with the OpenAPI community, such as: * Contributor: Includes but is not limited to any [contributor to the specification](https://github.com/OAI/OpenAPI-Specification/graphs/contributors) via an accepted pull request or who participates in issues or TSC calls. * Implementer: any person involved in the creation or maintenance of tooling that leverages the current OpenAPI Specification * Ambassador: represents the OpenAPI Specification to the developer community. This could be through talks at conferences or meetups, blog posts, or answering questions in places like Twitter, Stack Overflow, or the GitHub repo. * Supporter: uses the specification and appreciates its value. OpenAPI-Specification-3.1.0/GOVERNANCE.md000066400000000000000000000065761401301652500175100ustar00rootroot00000000000000# Governance The OpenAPI Specification is a project of the OpenAPI Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance). # Processes and procedures of the Technical Steering Committee (TSC) The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines. ## 1. The establishment of roles and the responsibilities for each role Roles: * [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the OAI's Business Governing Board (BGB) at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC. * [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. * [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members. ## 2. Adding members to the TSC A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner through [@OpenApiSpec](https://twitter.com/OpenApiSpec) on Twitter, assuming the TSC membership is not already at its maximum. A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting. A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting. Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 4-6 weeks (to be determined at start of each nominating period), though nominees have no voting rights. The provisional period is concluded by a second, confidential vote similar to the nomination period's vote. At most there are four voting periods per year (no more than one every three months), with a minimum of one per year. ## 3. Removal of membership from the TSC In dire situations, it may be necessary to remove a TSC member, such as behavior that violates the code of conduct (NB: whether non-participation merits removal is a decision left to the TSC voting members). 75% vote (confidential, electronic) of the other TSC members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the Liaison of their effective resignation date. ## 4. Criteria for decisions The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the OAI's Technical Oversight Board (TOB). The TSC will maintain a publicly available document specifying the process in the contributor guidelines for how proposed changes are merged into the specification. The TSC will document and publicize the schedule of merge parties and release parties for the benefit of the developer community. OpenAPI-Specification-3.1.0/IMPLEMENTATIONS.md000066400000000000000000000273351401301652500203250ustar00rootroot00000000000000### Implementations Below is a list of known tooling that implements the 3.0.0 specification. While support for the 3.0.0 specification matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the 3.x specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. These tools are not endorsed by the OAI. #### Low-Level tooling | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | swagger-parser | [github/swagger-api](https://github.com/swagger-api/swagger-parser) | Java | Swagger 1.0, 1.1, 1.2, 2.0 to OpenAPI Specification converter | | swagger-models | [github/swagger-api](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models) | Java | OpenAPI 3.0 Java Pojos | | springdoc-openapi | [github/springdoc/springdoc-openapi](https://github.com/springdoc/springdoc-openapi) | Java | Library that produces OpenAPI 3.x specification documentation for spring-boot applications. | | KaiZen OpenAPI Parser | [github/RepreZen/KaiZen-OpenAPI-Parser](https://github.com/RepreZen/KaiZen-OpenAPI-Parser) | Java | High-performance Parser, Validator, and Java Object Model for OpenAPI 3.x | | openapi3-ts | [github/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts | | swagger2openapi | [github/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator | | Microsoft.OpenApi.net | [github/microsoft/OpenApi.net](https://github.com/microsoft/openapi.net/) | dotnet | C# based parser with definition validation and migration support from V2 | | odata-openapi | [github/oasis-tcs/odata-openapi](https://github.com/oasis-tcs/odata-openapi) | XSLT | OData 4.0 to OpenAPI 3.0.0 converter | | openapi3_parser | [github/kevindew/openapi3_parser](https://github.com/kevindew/openapi3_parser) | Ruby | A Ruby implementation of parser and validator for the OpenAPI 3 Specification | | oas_parser | [github/Nexmo/oas_parser](https://github.com/Nexmo/oas_parser) | Ruby | An open source OpenAPI Spec 3 Definition Parser written in Ruby | | oas3-remote-refs | [github//OverSpeedIO/oas3-remote-refs](https://github.com/OverSpeedIO/oas3-remote-refs) | Node.js | Tool to pull remote references and merge them into the definitions of the provided OpenAPI3 specification. | go-openapi | [github/nasa9084/go-openapi](https://github.com/nasa9084/go-openapi) | Go | Golang struct model for OpenAPI 3.x. | | openapi | [github/wzshiming/openapi](https://github.com/wzshiming/openapi) | Go | OpenAPI 3 Specification for golang | | kin-openapi | [github/getkin/kin-openapi](https://github.com/getkin/kin-openapi) | Go | OpenAPI 3.x implementation for Go (parsing, converting, validation) | | Spectral | [github/stoplightio/spectral](https://github.com/stoplightio/spectral) | TypeScript, JavaScript | A flexible JSON object linter with out of the box support for OpenAPI Specification 2 and 3 | | openapi-validator | [gitlab/mmal/openapi-validator](https://gitlab.com/mmalawski/openapi-validator) | PHP | Validates response against OpenAPI schema | | OpenAPI-Delphi | [github/paolo-rossi/OpenAPI-Delphi](https://github.com/paolo-rossi/OpenAPI-Delphi) | Delphi | Delphi implementation of a generator, parser and validator for the OpenAPI 3 Specification | | spring-openapi | [github/jrcodeza/spring-openapi](https://github.com/jrcodeza/spring-openapi) | Java | OpenAPI v3 generator for Java Spring. Includes also client generation. Supports inheritance with discriminators and Jackson annotations and custom interceptors. | #### Editors | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | Visual Studio Code extension | [VS Code marketplace / OpenAPI (Swagger) editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) | TypeScript | Extends VS Code to provide OpenAPI 2.0 and 3.0 navigation, code snippets, new API creation | | Apicurio Studio | [github/Apicurio/apicurio-studio](https://github.com/Apicurio/apicurio-studio) | Java/TypeScript | Web-Based **visual designer** for OpenAPI 2.0 and 3.0.0. | | KaiZen OpenAPI Editor | [github/RepreZen/KaiZen-OpenAPI-Editor](https://github.com/RepreZen/KaiZen-OpenAPI-Editor) | Java | Eclipse Editor for OpenAPI 2.0 and 3.0 | | RepreZen API Studio | [RepreZen.com/OpenAPI](https://www.reprezen.com/OpenAPI) | Java | Commercial desktop IDE for API design, documentation & development | | OpenAPI-gui | [github/Mermade/openapi-gui](https://github.com/Mermade/openapi-gui) | Node.js | GUI / visual editor for creating and editing OpenAPI definitions | | SwaggerHub | [swaggerhub.com](https://swaggerhub.com) | | API Design and Documentation Platform, Built For Teams | swagger-editor | [github/swagger-api](https://github.com/swagger-api/swagger-editor) | JavaScript | Web-Based editor for creating, editing, validating and testing OpenAPI\Swagger definitions | | Remain OpenAPI Studio | Direct download: https://remainsoftware.com/extranet/download-type/openapi-studio-download
Or via Eclipse MarketPlace https://marketplace.eclipse.org/content/openapi-studio-rich-oas3-editor | Java | A user-friendly, visually rich studio supporting all features defined by the OpenAPI 3. Easy but powerful UI-based components creation, API testing, import, export, code generation and much more. | #### User Interfaces | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | openapi-viewer | [github/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. | | swagger-ui | [github/swagger-api](https://github.com/swagger-api/swagger-UI) | JavaScript | Web-Based interface for visualizing and testing OpenAPI\Swagger definitions | | lincoln | [github/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for OpenAPI v3 | | WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | JavaScript | Includes a native OpenAPI v3 UI which allows for customization of its banners and URL | | Widdershins | [github/Mermade/widdershins](https://github.com/Mermade/widdershins) | Node.js | Generate Slate/Shins markdown from OpenAPI 3.0.x | | angular-swagger-ui | [github/angular-swagger-ui](https://github.com/Orange-OpenSource/angular-swagger-ui) | AngularJS | An angularJS implementation of Swagger UI | | Redoc | [github/Redocly/redoc](https://github.com/Redocly/redoc) | JavaScript | A React-based renderer with deep support for OAS v2 and v3 and zero dev-dependency| #### Mock Servers | Title | Project Link | Language | Description | | -------------- | ------------ | -------- | ----------- | | API Sprout | [github/danielgtaylor/apisprout](https://github.com/danielgtaylor/apisprout) | Go | Lightweight, blazing fast, cross-platform OpenAPI 3 mock server with validation | #### Server Implementations | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | Vert.x Web API Contract | [github/vert-x3/vertx-web](http://vertx.io/docs/#web) | Java, Kotlin, JavaScript, Groovy, Ruby, Ceylon & Scala | Create an API endpoint with Vert.x 3 and OpenAPI 3 with automatic requests validation | Fusio | [github/apioo/fusio](https://github.com/apioo/fusio) | PHP, JavaScript | Build API endpoints based on OpenAPI 3 | Modern | [github/modern-project/modern-ruby](https://github.com/modern-project/modern-ruby) | Ruby | OpenAPI 3-based Rack framework with automatic OAS generation and requests/response validation | Koa2-OAS3 | [github/OverSpeedIO/koa2-oas3](https://github.com/OverSpeedIO/koa2-oas3) | Node.js | OpenAPI 3 request validation middleware for Koa2 based apps. | Exegesis | [github/exegesis-js/exegesis](https://github.com/exegesis-js/exegesis) | Node.js | OpenAPI 3 server-side framework for express and other frameworks. | PHP-CRUD-API | [github/mevdschee/php-crud-api](https://github.com/mevdschee/php-crud-api) | PHP | Automatic CRUD API with OpenAPI 3 docs | FastAPI | [github/tiangolo/fastapi](https://github.com/tiangolo/fastapi) | Python | OpenAPI 3 based, high performance, Python 3.6+ API framework with automatic data validation, serialization and great editor support. | Fastify OpenAPI v3 | [gitlab.com/m03geek/fastify-oas](https://gitlab.com/m03geek/fastify-oas) | Node.JS | Fastify OpenAPI v3+ plugin. Generates OpenAPI specification from fastify schemas and routes. Also serves swagger ui and spec in json/yaml formats. | openapi-backend | [github/anttiviljami/openapi-backend](https://github.com/anttiviljami/openapi-backend) | Node.js, TypeScript | Build, Validate, Route, and Mock in the backend using OpenAPI v3 spec in your favourite framework #### Client Implementations | Title | Project Link | Language | Description | |----------------|--------------|----------|-------------| | Scorpio | [github/notEthan/scorpio](https://github.com/notEthan/Scorpio) | Ruby | OpenAPI 2 and 3 implementation offering a HTTP client library | | openapi-client-axios | [github/anttiviljami/openapi-client-axios](https://github.com/anttiviljami/openapi-client-axios) | JavaScript, TypeScript | JavaScript client library for consuming OpenAPI-enabled APIs with axios. Types included. #### Code Generators | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| | baucis-openapi3 | [github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. | | Google Gnostic | [github/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. | | Gen | [github/wzshiming/gen](https://github.com/wzshiming/gen) | Go | Generate OpenAPI 3, client, and route based on golang source code. | | serverless-openapi-documentation | [github/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | TypeScript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration | | zero-rails_openapi | [github/zhandao/zero-rails_openapi](https://github.com/zhandao/zero-rails_openapi) | Ruby | Provide concise DSL for generating the OpenAPI Specification 3 documentation file for Rails application | | slush-vertx | [github/pmlopes/slush-vertx](https://github.com/pmlopes/slush-vertx) | Java, Kotlin & Groovy | Generate server skeleton for [Vert.x Web API Contract](http://vertx.io/docs/#web) and API Client based on [Vert.x 3 Web Client](http://vertx.io/docs/#web) | WebSphere Liberty | [Download jar](https://developer.ibm.com/wasdev/downloads/) | Java EE | Generates OpenAPI v3 documentation from Java EE applications | | swagger-node-codegen | [github/fmvilas/swagger-node-codegen](https://github.com/fmvilas/swagger-node-codegen) | Node.js | Generates a Node.js/express server, but also has a template engine for creating any templates needed. | .NET-C#-Annotations | [github/Microsoft/OpenAPI-NET-CSharpAnnotations](https://github.com/Microsoft/OpenAPI.NET.CSharpAnnotations) | dotnet | Convert your native C# comments/annotation XML from your API code into a OpenAPI document object. | | Object Oriented OpenAPI Specification | [github/goldspecdigital/oooas](https://github.com/goldspecdigital/oooas) | PHP | Generates OpenAPI documents using PHP. | OpenAPI-Specification-3.1.0/LICENSE000066400000000000000000000261211401301652500165300ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright The Linux Foundation Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. OpenAPI-Specification-3.1.0/MAINTAINERS.md000066400000000000000000000007411401301652500176170ustar00rootroot00000000000000## Active * Darrel Miller [@darrelmiller](https://github.com/darrelmiller) * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc) * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh) * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson) * Ron Ratovsky [@webron](https://github.com/webron) * Uri Sarid [@usarid](https://github.com/usarid) ## Emeritus * Jason Harmon [@jharmn](https://github.com/jharmn) * Tony Tam [@fehguy](https://github.com/fehguy) OpenAPI-Specification-3.1.0/README.md000066400000000000000000000122651401301652500170060ustar00rootroot00000000000000# The OpenAPI Specification ![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases. OpenAPI documents describe an APIs services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application. The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service – the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI – this specification is not intended to cover every possible style of HTTP APIs, but does include support for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer). The OpenAPI Specification does not mandate a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a HTTP API. This GitHub project is the starting point for OpenAPI. Here you will find the information you need about the OpenAPI Specification, simple examples of what it looks like, and some general information regarding the project. ## Current Version - 3.1.0 The current version of the OpenAPI specification is [OpenAPI Specification 3.1.0](versions/3.1.0.md). ### Previous Versions This repository also contains all [previous versions](versions). Each folder in this repository, such as [examples](examples) and [schemas](schemas), should contain folders pertaining to the current and previous versions of the specification. ## See It in Action If you just want to see it work, check out the [list of current examples](examples). ## Tools and Libraries Looking to see how you can create your own OpenAPI definition, present it, or otherwise use it? Check out the growing [list of implementations](IMPLEMENTATIONS.md). ## Participation The current process for development of the OpenAPI Specification is described in [Development Guidelines](DEVELOPMENT.md). Development of the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to master. The TSC holds weekly web conferences to review open pull requests and discuss open issues related to the evolving OpenAPI Specification. Participation in weekly calls and scheduled working sessions is open to the community. You can view the [TSC calendar online](https://openapi.groups.io/g/tsc/calendar), and import it to your calendar using the [iCal link](https://openapi.groups.io/g/tsc/ics/1105671/1995679554/feed.ics). The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the OpenAPI Specification, consider taking the following actions: * Review the [current specification](versions/3.1.0.md). The human-readable markdown file _is the source of truth_ for the specification. * Review the [development](DEVELOPMENT.md) process so you understand how the spec is evolving. * Check the [issues](https://github.com/OAI/OpenAPI-Specification/issues) and [pull requests](https://github.com/OAI/OpenAPI-Specification/pulls) to see if someone has already documented your idea or feedback on the specification. You can follow an existing conversation by subscribing to the existing issue or PR. * Create an issue to describe a new concern. If possible, propose a solution. Not all feedback can be accommodated and there may be solid arguments for or against a change being appropriate for the specification. ## Licensing See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE) ![Analytics](https://ga-beacon.appspot.com/UA-831873-42/readme.md?pixel) OpenAPI-Specification-3.1.0/TOB.md000066400000000000000000000010221401301652500164620ustar00rootroot00000000000000# Technical Oversight Board ("TOB") ## Description: > The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter. ## TSC Elected - terms through May 2021 Isabelle Mauny @isamauny Uri Sarid @usarid Marsh Gardiner @earth2marsh Ron Ratovsky @webron ## BGB Elected - terms through May 2022 Darrel Miller @darrelmiller Jerome Louvel @jlouvel Jeremy Whitlock @whitlockjc OpenAPI-Specification-3.1.0/examples/000077500000000000000000000000001401301652500173375ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/000077500000000000000000000000001401301652500200245ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/json/000077500000000000000000000000001401301652500207755ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/json/api-with-examples.json000066400000000000000000000117221401301652500252310ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "title": "Simple API overview", "version": "v2" }, "paths": { "/": { "get": { "operationId": "listVersionsv2", "summary": "List API versions", "produces": [ "application/json" ], "responses": { "200": { "description": "200 300 response", "examples": { "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" } }, "300": { "description": "200 300 response", "examples": { "application/json": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}" } } } } }, "/v2": { "get": { "operationId": "getVersionDetailsv2", "summary": "Show API version details", "produces": [ "application/json" ], "responses": { "200": { "description": "200 203 response", "examples": { "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" } }, "203": { "description": "200 203 response", "examples": { "application/json": "{\n \"version\": {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"media-types\": [\n {\n \"base\": \"application/xml\",\n \"type\": \"application/vnd.openstack.compute+xml;version=2\"\n },\n {\n \"base\": \"application/json\",\n \"type\": \"application/vnd.openstack.compute+json;version=2\"\n }\n ],\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://23.253.228.211:8774/v2/\",\n \"rel\": \"self\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf\",\n \"type\": \"application/pdf\",\n \"rel\": \"describedby\"\n },\n {\n \"href\": \"http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl\",\n \"type\": \"application/vnd.sun.wadl+xml\",\n \"rel\": \"describedby\"\n }\n ]\n }\n}" } } } } } }, "consumes": [ "application/json" ] }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-expanded.json000066400000000000000000000144511401301652500253300ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team", "email": "apiteam@swagger.io", "url": "http://swagger.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", "operationId": "findPets", "parameters": [ { "name": "tags", "in": "query", "description": "tags to filter by", "required": false, "type": "array", "collectionFormat": "csv", "items": { "type": "string" } }, { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "description": "Creates a new pet in the store. Duplicates are allowed", "operationId": "addPet", "parameters": [ { "name": "pet", "in": "body", "description": "Pet to add to the store", "required": true, "schema": { "$ref": "#/definitions/NewPet" } } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/pets/{id}": { "get": { "description": "Returns a user based on a single ID, if the user does not have access to the pet", "operationId": "find pet by id", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to fetch", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }, "delete": { "description": "deletes a single pet based on the ID supplied", "operationId": "deletePet", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to delete", "required": true, "type": "integer", "format": "int64" } ], "responses": { "204": { "description": "pet deleted" }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } } }, "definitions": { "Pet": { "type": "object", "allOf": [ { "$ref": "#/definitions/NewPet" }, { "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64" } } } ] }, "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "tag": { "type": "string" } } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } } OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-minimal.json000066400000000000000000000025331401301652500251640ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team" }, "license": { "name": "MIT" } }, "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "produces": [ "application/json" ], "responses": { "200": { "description": "A list of pets.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } } } } } }, "definitions": { "Pet": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } } }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/000077500000000000000000000000001401301652500244445ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/common/000077500000000000000000000000001401301652500257345ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/common/Error.json000066400000000000000000000003201401301652500277130ustar00rootroot00000000000000{ "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/spec/000077500000000000000000000000001401301652500253765ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/spec/NewPet.json000066400000000000000000000004001401301652500274650ustar00rootroot00000000000000{ "type": "object", "allOf": [ { "$ref": "Pet.json" }, { "required": [ "name" ], "properties": { "description": { "type": "integer", "format": "int64" } } } ] }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/spec/Pet.json000066400000000000000000000003611401301652500270210ustar00rootroot00000000000000{ "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/spec/parameters.json000066400000000000000000000006341401301652500304370ustar00rootroot00000000000000{ "tagsParam": { "name": "tags", "in": "query", "description": "tags to filter by", "required": false, "type": "array", "collectionFormat": "csv", "items": { "type": "string" } }, "limitsParam": { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-separate/spec/swagger.json000066400000000000000000000120321401301652500277260ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team", "email": "apiteam@swagger.io", "url": "http://swagger.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", "operationId": "findPets", "parameters": [ { "$ref": "parameters.json#/tagsParam" }, { "$ref": "parameters.json#/limitsParam" } ], "responses": { "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "Pet.json" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "../common/Error.json" } } } }, "post": { "description": "Creates a new pet in the store. Duplicates are allowed", "operationId": "addPet", "parameters": [ { "name": "pet", "in": "body", "description": "Pet to add to the store", "required": true, "schema": { "$ref": "NewPet.json" } } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "Pet.json" } }, "default": { "description": "unexpected error", "schema": { "$ref": "../common/Error.json" } } } } }, "/pets/{id}": { "get": { "description": "Returns a user based on a single ID, if the user does not have access to the pet", "operationId": "find pet by id", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to fetch", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "Pet.json" } }, "default": { "description": "unexpected error", "schema": { "$ref": "../common/Error.json" } } } }, "delete": { "description": "deletes a single pet based on the ID supplied", "operationId": "deletePet", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to delete", "required": true, "type": "integer", "format": "int64" } ], "responses": { "204": { "description": "pet deleted" }, "default": { "description": "unexpected error", "schema": { "$ref": "../common/Error.json" } } } } } } } OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-simple.json000066400000000000000000000121051401301652500250230ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team" }, "license": { "name": "MIT" } }, "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "operationId": "findPets", "produces": [ "application/json", "application/xml", "text/xml", "text/html" ], "parameters": [ { "name": "tags", "in": "query", "description": "tags to filter by", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "csv" }, { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } }, "post": { "description": "Creates a new pet in the store. Duplicates are allowed", "operationId": "addPet", "produces": [ "application/json" ], "parameters": [ { "name": "pet", "in": "body", "description": "Pet to add to the store", "required": true, "schema": { "$ref": "#/definitions/NewPet" } } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } } }, "/pets/{id}": { "get": { "description": "Returns a user based on a single ID, if the user does not have access to the pet", "operationId": "findPetById", "produces": [ "application/json", "application/xml", "text/xml", "text/html" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to fetch", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } }, "delete": { "description": "deletes a single pet based on the ID supplied", "operationId": "deletePet", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to delete", "required": true, "type": "integer", "format": "int64" } ], "responses": { "204": { "description": "pet deleted" }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } } } }, "definitions": { "Pet": { "type": "object", "allOf": [ { "$ref": "#/definitions/NewPet" }, { "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64" } } } ] }, "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "tag": { "type": "string" } } }, "ErrorModel": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } }OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore-with-external-docs.json000066400000000000000000000126771401301652500272710ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team", "email": "apiteam@swagger.io", "url": "http://swagger.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "find more info here", "url": "https://swagger.io/about" }, "host": "petstore.swagger.io", "basePath": "/api", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "operationId": "findPets", "externalDocs": { "description": "find more info here", "url": "https://swagger.io/about" }, "produces": [ "application/json", "application/xml", "text/xml", "text/html" ], "parameters": [ { "name": "tags", "in": "query", "description": "tags to filter by", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "csv" }, { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } }, "post": { "description": "Creates a new pet in the store. Duplicates are allowed", "operationId": "addPet", "produces": [ "application/json" ], "parameters": [ { "name": "pet", "in": "body", "description": "Pet to add to the store", "required": true, "schema": { "$ref": "#/definitions/NewPet" } } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } } }, "/pets/{id}": { "get": { "description": "Returns a user based on a single ID, if the user does not have access to the pet", "operationId": "findPetById", "produces": [ "application/json", "application/xml", "text/xml", "text/html" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to fetch", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "pet response", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } }, "delete": { "description": "deletes a single pet based on the ID supplied", "operationId": "deletePet", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to delete", "required": true, "type": "integer", "format": "int64" } ], "responses": { "204": { "description": "pet deleted" }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } } } }, "definitions": { "Pet": { "type": "object", "allOf": [ { "$ref": "#/definitions/NewPet" }, { "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64" } } } ] }, "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "tag": { "type": "string" } } }, "ErrorModel": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } } OpenAPI-Specification-3.1.0/examples/v2.0/json/petstore.json000066400000000000000000000062251401301652500235420ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "license": { "name": "MIT" } }, "host": "petstore.swagger.io", "basePath": "/v1", "schemes": [ "http" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/pets": { "get": { "summary": "List all pets", "operationId": "listPets", "tags": [ "pets" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many items to return at one time (max 100)", "required": false, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "An paged array of pets", "headers": { "x-next": { "type": "string", "description": "A link to the next page of responses" } }, "schema": { "$ref": "#/definitions/Pets" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } }, "post": { "summary": "Create a pet", "operationId": "createPets", "tags": [ "pets" ], "responses": { "201": { "description": "Null response" }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/pets/{petId}": { "get": { "summary": "Info for a specific pet", "operationId": "showPetById", "tags": [ "pets" ], "parameters": [ { "name": "petId", "in": "path", "required": true, "description": "The id of the pet to retrieve", "type": "string" } ], "responses": { "200": { "description": "Expected response to a valid request", "schema": { "$ref": "#/definitions/Pets" } }, "default": { "description": "unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } } }, "definitions": { "Pet": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } }, "Pets": { "type": "array", "items": { "$ref": "#/definitions/Pet" } }, "Error": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } }OpenAPI-Specification-3.1.0/examples/v2.0/json/uber.json000066400000000000000000000266371401301652500226430ustar00rootroot00000000000000{ "swagger": "2.0", "info": { "title": "Uber API", "description": "Move your app forward with the Uber API", "version": "1.0.0" }, "host": "api.uber.com", "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], "paths": { "/products": { "get": { "summary": "Product Types", "description": "The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.", "parameters": [ { "name": "latitude", "in": "query", "description": "Latitude component of location.", "required": true, "type": "number", "format": "double" }, { "name": "longitude", "in": "query", "description": "Longitude component of location.", "required": true, "type": "number", "format": "double" } ], "tags": [ "Products" ], "responses": { "200": { "description": "An array of products", "schema": { "type": "array", "items": { "$ref": "#/definitions/Product" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/estimates/price": { "get": { "summary": "Price Estimates", "description": "The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.", "parameters": [ { "name": "start_latitude", "in": "query", "description": "Latitude component of start location.", "required": true, "type": "number", "format": "double" }, { "name": "start_longitude", "in": "query", "description": "Longitude component of start location.", "required": true, "type": "number", "format": "double" }, { "name": "end_latitude", "in": "query", "description": "Latitude component of end location.", "required": true, "type": "number", "format": "double" }, { "name": "end_longitude", "in": "query", "description": "Longitude component of end location.", "required": true, "type": "number", "format": "double" } ], "tags": [ "Estimates" ], "responses": { "200": { "description": "An array of price estimates by product", "schema": { "type": "array", "items": { "$ref": "#/definitions/PriceEstimate" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/estimates/time": { "get": { "summary": "Time Estimates", "description": "The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.", "parameters": [ { "name": "start_latitude", "in": "query", "description": "Latitude component of start location.", "required": true, "type": "number", "format": "double" }, { "name": "start_longitude", "in": "query", "description": "Longitude component of start location.", "required": true, "type": "number", "format": "double" }, { "name": "customer_uuid", "in": "query", "type": "string", "format": "uuid", "description": "Unique customer identifier to be used for experience customization." }, { "name": "product_id", "in": "query", "type": "string", "description": "Unique identifier representing a specific product for a given latitude & longitude." } ], "tags": [ "Estimates" ], "responses": { "200": { "description": "An array of products", "schema": { "type": "array", "items": { "$ref": "#/definitions/Product" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/me": { "get": { "summary": "User Profile", "description": "The User Profile endpoint returns information about the Uber user that has authorized with the application.", "tags": [ "User" ], "responses": { "200": { "description": "Profile information for a user", "schema": { "$ref": "#/definitions/Profile" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } }, "/history": { "get": { "summary": "User Activity", "description": "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.", "parameters": [ { "name": "offset", "in": "query", "type": "integer", "format": "int32", "description": "Offset the list of returned results by this amount. Default is zero." }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "description": "Number of items to retrieve. Default is 5, maximum is 100." } ], "tags": [ "User" ], "responses": { "200": { "description": "History information for the given user", "schema": { "$ref": "#/definitions/Activities" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } } }, "definitions": { "Product": { "properties": { "product_id": { "type": "string", "description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles." }, "description": { "type": "string", "description": "Description of product." }, "display_name": { "type": "string", "description": "Display name of product." }, "capacity": { "type": "string", "description": "Capacity of product. For example, 4 people." }, "image": { "type": "string", "description": "Image URL representing the product." } } }, "PriceEstimate": { "properties": { "product_id": { "type": "string", "description": "Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles" }, "currency_code": { "type": "string", "description": "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code." }, "display_name": { "type": "string", "description": "Display name of product." }, "estimate": { "type": "string", "description": "Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or \"Metered\" for TAXI." }, "low_estimate": { "type": "number", "description": "Lower bound of the estimated price." }, "high_estimate": { "type": "number", "description": "Upper bound of the estimated price." }, "surge_multiplier": { "type": "number", "description": "Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier." } } }, "Profile": { "properties": { "first_name": { "type": "string", "description": "First name of the Uber user." }, "last_name": { "type": "string", "description": "Last name of the Uber user." }, "email": { "type": "string", "description": "Email address of the Uber user" }, "picture": { "type": "string", "description": "Image URL of the Uber user." }, "promo_code": { "type": "string", "description": "Promo code of the Uber user." } } }, "Activity": { "properties": { "uuid": { "type": "string", "description": "Unique identifier for the activity" } } }, "Activities": { "properties": { "offset": { "type": "integer", "format": "int32", "description": "Position in pagination." }, "limit": { "type": "integer", "format": "int32", "description": "Number of items to retrieve (100 max)." }, "count": { "type": "integer", "format": "int32", "description": "Total number of items available." }, "history": { "type": "array", "items": { "$ref": "#/definitions/Activity" } } } }, "Error": { "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "fields": { "type": "string" } } } } }OpenAPI-Specification-3.1.0/examples/v2.0/yaml/000077500000000000000000000000001401301652500207665ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/yaml/api-with-examples.yaml000066400000000000000000000137271401301652500252220ustar00rootroot00000000000000swagger: "2.0" info: title: Simple API overview version: v2 paths: /: get: operationId: listVersionsv2 summary: List API versions produces: - application/json responses: "200": description: |- 200 300 response examples: application/json: |- { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self" } ] } ] } "300": description: |- 200 300 response examples: application/json: |- { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self" } ] } ] } /v2: get: operationId: getVersionDetailsv2 summary: Show API version details produces: - application/json responses: "200": description: |- 200 203 response examples: application/json: |- { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } "203": description: |- 200 203 response examples: application/json: |- { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://23.253.228.211:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } consumes: - application/json OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-expanded.yaml000066400000000000000000000065761401301652500253230ustar00rootroot00000000000000swagger: "2.0" info: version: 1.0.0 title: Swagger Petstore description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification termsOfService: http://swagger.io/terms/ contact: name: Swagger API Team email: apiteam@swagger.io url: http://swagger.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html host: petstore.swagger.io basePath: /api schemes: - http consumes: - application/json produces: - application/json paths: /pets: get: description: | Returns all pets from the system that the user has access to operationId: findPets parameters: - name: tags in: query description: tags to filter by required: false type: array collectionFormat: csv items: type: string - name: limit in: query description: maximum number of results to return required: false type: integer format: int32 responses: "200": description: pet response schema: type: array items: $ref: '#/definitions/Pet' default: description: unexpected error schema: $ref: '#/definitions/Error' post: description: Creates a new pet in the store. Duplicates are allowed operationId: addPet parameters: - name: pet in: body description: Pet to add to the store required: true schema: $ref: '#/definitions/NewPet' responses: "200": description: pet response schema: $ref: '#/definitions/Pet' default: description: unexpected error schema: $ref: '#/definitions/Error' /pets/{id}: get: description: Returns a user based on a single ID, if the user does not have access to the pet operationId: find pet by id parameters: - name: id in: path description: ID of pet to fetch required: true type: integer format: int64 responses: "200": description: pet response schema: $ref: '#/definitions/Pet' default: description: unexpected error schema: $ref: '#/definitions/Error' delete: description: deletes a single pet based on the ID supplied operationId: deletePet parameters: - name: id in: path description: ID of pet to delete required: true type: integer format: int64 responses: "204": description: pet deleted default: description: unexpected error schema: $ref: '#/definitions/Error' definitions: Pet: allOf: - $ref: '#/definitions/NewPet' - required: - id type: "object" properties: id: type: integer format: int64 NewPet: type: "object" required: - name properties: name: type: string tag: type: string Error: type: "object" required: - code - message properties: code: type: integer format: int32 message: type: string OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-minimal.yaml000066400000000000000000000021141401301652500251410ustar00rootroot00000000000000--- swagger: "2.0" info: version: "1.0.0" title: "Swagger Petstore" description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" termsOfService: "http://swagger.io/terms/" contact: name: "Swagger API Team" license: name: "MIT" host: "petstore.swagger.io" basePath: "/api" schemes: - "http" consumes: - "application/json" produces: - "application/json" paths: /pets: get: description: "Returns all pets from the system that the user has access to" produces: - "application/json" responses: "200": description: "A list of pets." schema: type: "array" items: $ref: "#/definitions/Pet" definitions: Pet: type: "object" required: - "id" - "name" properties: id: type: "integer" format: "int64" name: type: "string" tag: type: "string" OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/000077500000000000000000000000001401301652500244355ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/common/000077500000000000000000000000001401301652500257255ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/common/Error.yaml000066400000000000000000000002001401301652500276720ustar00rootroot00000000000000type: object required: - code - message properties: code: type: integer format: int32 message: type: string OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/spec/000077500000000000000000000000001401301652500253675ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/spec/NewPet.yaml000066400000000000000000000002231401301652500274520ustar00rootroot00000000000000type: object allOf: - $ref: 'Pet.yaml' - required: - name properties: description: type: integer format: int64 OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/spec/Pet.yaml000066400000000000000000000002161401301652500270020ustar00rootroot00000000000000type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/spec/parameters.yaml000066400000000000000000000004431401301652500304170ustar00rootroot00000000000000tagsParam: name: tags in: query description: tags to filter by required: false type: array collectionFormat: csv items: type: string limitsParam: name: limit in: query description: maximum number of results to return required: false type: integer format: int32 OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-separate/spec/swagger.yaml000066400000000000000000000077561401301652500277310ustar00rootroot00000000000000swagger: "2.0" info: version: 1.0.0 title: Swagger Petstore description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification termsOfService: http://swagger.io/terms/ contact: name: Swagger API Team email: apiteam@swagger.io url: http://swagger.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html host: petstore.swagger.io basePath: /api schemes: - http consumes: - application/json produces: - application/json paths: /pets: get: description: | Returns all pets from the system that the user has access to Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. operationId: findPets parameters: - $ref: 'parameters.yaml#/tagsParam' - $ref: 'parameters.yaml#/limitsParam' responses: "200": description: pet response schema: type: array items: $ref: 'Pet.yaml' default: description: unexpected error schema: $ref: '../common/Error.yaml' post: description: Creates a new pet in the store. Duplicates are allowed operationId: addPet parameters: - name: pet in: body description: Pet to add to the store required: true schema: $ref: 'NewPet.yaml' responses: "200": description: pet response schema: $ref: 'Pet.yaml' default: description: unexpected error schema: $ref: '../common/Error.yaml' /pets/{id}: get: description: Returns a user based on a single ID, if the user does not have access to the pet operationId: find pet by id parameters: - name: id in: path description: ID of pet to fetch required: true type: integer format: int64 responses: "200": description: pet response schema: $ref: 'Pet.yaml' default: description: unexpected error schema: $ref: '../common/Error.yaml' delete: description: deletes a single pet based on the ID supplied operationId: deletePet parameters: - name: id in: path description: ID of pet to delete required: true type: integer format: int64 responses: "204": description: pet deleted default: description: unexpected error schema: $ref: '../common/Error.yaml' OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-simple.yaml000066400000000000000000000101231401301652500250030ustar00rootroot00000000000000--- swagger: "2.0" info: version: "1.0.0" title: "Swagger Petstore" description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" termsOfService: "http://swagger.io/terms/" contact: name: "Swagger API Team" license: name: "MIT" host: "petstore.swagger.io" basePath: "/api" schemes: - "http" consumes: - "application/json" produces: - "application/json" paths: /pets: get: description: "Returns all pets from the system that the user has access to" operationId: "findPets" produces: - "application/json" - "application/xml" - "text/xml" - "text/html" parameters: - name: "tags" in: "query" description: "tags to filter by" required: false type: "array" items: type: "string" collectionFormat: "csv" - name: "limit" in: "query" description: "maximum number of results to return" required: false type: "integer" format: "int32" responses: "200": description: "pet response" schema: type: "array" items: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" post: description: "Creates a new pet in the store. Duplicates are allowed" operationId: "addPet" produces: - "application/json" parameters: - name: "pet" in: "body" description: "Pet to add to the store" required: true schema: $ref: "#/definitions/NewPet" responses: "200": description: "pet response" schema: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" /pets/{id}: get: description: "Returns a user based on a single ID, if the user does not have access to the pet" operationId: "findPetById" produces: - "application/json" - "application/xml" - "text/xml" - "text/html" parameters: - name: "id" in: "path" description: "ID of pet to fetch" required: true type: "integer" format: "int64" responses: "200": description: "pet response" schema: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" delete: description: "deletes a single pet based on the ID supplied" operationId: "deletePet" parameters: - name: "id" in: "path" description: "ID of pet to delete" required: true type: "integer" format: "int64" responses: "204": description: "pet deleted" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" definitions: Pet: type: "object" allOf: - $ref: "#/definitions/NewPet" - required: - "id" properties: id: type: "integer" format: "int64" NewPet: type: "object" required: - "name" properties: name: type: "string" tag: type: "string" ErrorModel: type: "object" required: - "code" - "message" properties: code: type: "integer" format: "int32" message: type: "string" OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore-with-external-docs.yaml000066400000000000000000000106431401301652500272420ustar00rootroot00000000000000--- swagger: "2.0" info: version: "1.0.0" title: "Swagger Petstore" description: "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification" termsOfService: "http://swagger.io/terms/" contact: name: "Swagger API Team" email: "apiteam@swagger.io" url: "http://swagger.io" license: name: "Apache 2.0" url: "https://www.apache.org/licenses/LICENSE-2.0.html" externalDocs: description: "find more info here" url: "https://swagger.io/about" host: "petstore.swagger.io" basePath: "/api" schemes: - "http" consumes: - "application/json" produces: - "application/json" paths: /pets: get: description: "Returns all pets from the system that the user has access to" operationId: "findPets" externalDocs: description: "find more info here" url: "https://swagger.io/about" produces: - "application/json" - "application/xml" - "text/xml" - "text/html" parameters: - name: "tags" in: "query" description: "tags to filter by" required: false type: "array" items: type: "string" collectionFormat: "csv" - name: "limit" in: "query" description: "maximum number of results to return" required: false type: "integer" format: "int32" responses: "200": description: "pet response" schema: type: "array" items: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" post: description: "Creates a new pet in the store. Duplicates are allowed" operationId: "addPet" produces: - "application/json" parameters: - name: "pet" in: "body" description: "Pet to add to the store" required: true schema: $ref: "#/definitions/NewPet" responses: "200": description: "pet response" schema: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" /pets/{id}: get: description: "Returns a user based on a single ID, if the user does not have access to the pet" operationId: "findPetById" produces: - "application/json" - "application/xml" - "text/xml" - "text/html" parameters: - name: "id" in: "path" description: "ID of pet to fetch" required: true type: "integer" format: "int64" responses: "200": description: "pet response" schema: $ref: "#/definitions/Pet" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" delete: description: "deletes a single pet based on the ID supplied" operationId: "deletePet" parameters: - name: "id" in: "path" description: "ID of pet to delete" required: true type: "integer" format: "int64" responses: "204": description: "pet deleted" default: description: "unexpected error" schema: $ref: "#/definitions/ErrorModel" definitions: Pet: type: "object" allOf: - $ref: "#/definitions/NewPet" - required: - "id" properties: id: type: "integer" format: "int64" NewPet: type: "object" required: - "name" properties: name: type: "string" tag: type: "string" ErrorModel: type: "object" required: - "code" - "message" properties: code: type: "integer" format: "int32" message: type: "string" OpenAPI-Specification-3.1.0/examples/v2.0/yaml/petstore.yaml000066400000000000000000000042111401301652500235150ustar00rootroot00000000000000swagger: "2.0" info: version: 1.0.0 title: Swagger Petstore license: name: MIT host: petstore.swagger.io basePath: /v1 schemes: - http consumes: - application/json produces: - application/json paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false type: integer format: int32 responses: "200": description: A paged array of pets headers: x-next: type: string description: A link to the next page of responses schema: $ref: '#/definitions/Pets' default: description: unexpected error schema: $ref: '#/definitions/Error' post: summary: Create a pet operationId: createPets tags: - pets responses: "201": description: Null response default: description: unexpected error schema: $ref: '#/definitions/Error' /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById tags: - pets parameters: - name: petId in: path required: true description: The id of the pet to retrieve type: string responses: "200": description: Expected response to a valid request schema: $ref: '#/definitions/Pets' default: description: unexpected error schema: $ref: '#/definitions/Error' definitions: Pet: type: "object" required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Pets: type: array items: $ref: '#/definitions/Pet' Error: type: "object" required: - code - message properties: code: type: integer format: int32 message: type: string OpenAPI-Specification-3.1.0/examples/v2.0/yaml/uber.yaml000066400000000000000000000222631401301652500226140ustar00rootroot00000000000000# this is an example of the Uber API # as a demonstration of an API spec in YAML swagger: "2.0" info: title: Uber API description: Move your app forward with the Uber API version: "1.0.0" # the domain of the service host: api.uber.com # array of all schemes that your API supports schemes: - https # will be prefixed to all paths basePath: /v1 securityDefinitions: apikey: type: apiKey name: server_token in: query produces: - application/json paths: /products: get: summary: Product Types description: The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order. parameters: - name: latitude in: query description: Latitude component of location. required: true type: number format: double - name: longitude in: query description: Longitude component of location. required: true type: number format: double security: - apikey: [] tags: - Products responses: "200": description: An array of products schema: type: array items: $ref: '#/definitions/Product' default: description: Unexpected error schema: $ref: '#/definitions/Error' /estimates/price: get: summary: Price Estimates description: The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. parameters: - name: start_latitude in: query description: Latitude component of start location. required: true type: number format: double - name: start_longitude in: query description: Longitude component of start location. required: true type: number format: double - name: end_latitude in: query description: Latitude component of end location. required: true type: number format: double - name: end_longitude in: query description: Longitude component of end location. required: true type: number format: double tags: - Estimates responses: "200": description: An array of price estimates by product schema: type: array items: $ref: '#/definitions/PriceEstimate' default: description: Unexpected error schema: $ref: '#/definitions/Error' /estimates/time: get: summary: Time Estimates description: The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs. parameters: - name: start_latitude in: query description: Latitude component of start location. required: true type: number format: double - name: start_longitude in: query description: Longitude component of start location. required: true type: number format: double - name: customer_uuid in: query type: string format: uuid description: Unique customer identifier to be used for experience customization. - name: product_id in: query type: string description: Unique identifier representing a specific product for a given latitude & longitude. tags: - Estimates responses: "200": description: An array of products schema: type: array items: $ref: '#/definitions/Product' default: description: Unexpected error schema: $ref: '#/definitions/Error' /me: get: summary: User Profile description: The User Profile endpoint returns information about the Uber user that has authorized with the application. tags: - User responses: "200": description: Profile information for a user schema: $ref: '#/definitions/Profile' default: description: Unexpected error schema: $ref: '#/definitions/Error' /history: get: summary: User Activity description: The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. parameters: - name: offset in: query type: integer format: int32 description: Offset the list of returned results by this amount. Default is zero. - name: limit in: query type: integer format: int32 description: Number of items to retrieve. Default is 5, maximum is 100. tags: - User responses: "200": description: History information for the given user schema: $ref: '#/definitions/Activities' default: description: Unexpected error schema: $ref: '#/definitions/Error' definitions: Product: properties: product_id: type: string description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles. description: type: string description: Description of product. display_name: type: string description: Display name of product. capacity: type: integer description: Capacity of product. For example, 4 people. image: type: string description: Image URL representing the product. ProductList: properties: products: description: Contains the list of products type: array items: $ref: "#/definitions/Product" PriceEstimate: properties: product_id: type: string description: Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles currency_code: type: string description: "[ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code." display_name: type: string description: Display name of product. estimate: type: string description: Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or "Metered" for TAXI. low_estimate: type: number description: Lower bound of the estimated price. high_estimate: type: number description: Upper bound of the estimated price. surge_multiplier: type: number description: Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier. Profile: properties: first_name: type: string description: First name of the Uber user. last_name: type: string description: Last name of the Uber user. email: type: string description: Email address of the Uber user picture: type: string description: Image URL of the Uber user. promo_code: type: string description: Promo code of the Uber user. Activity: properties: uuid: type: string description: Unique identifier for the activity Activities: properties: offset: type: integer format: int32 description: Position in pagination. limit: type: integer format: int32 description: Number of items to retrieve (100 max). count: type: integer format: int32 description: Total number of items available. history: type: array items: $ref: '#/definitions/Activity' Error: properties: code: type: integer format: int32 message: type: string fields: type: string OpenAPI-Specification-3.1.0/examples/v3.0/000077500000000000000000000000001401301652500200255ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v3.0/api-with-examples.json000066400000000000000000000144271401301652500242660ustar00rootroot00000000000000{ "openapi": "3.0.0", "info": { "title": "Simple API overview", "version": "2.0.0" }, "paths": { "/": { "get": { "operationId": "listVersionsv2", "summary": "List API versions", "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "foo": { "value": { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self" } ] } ] } } } } } }, "300": { "description": "300 response", "content": { "application/json": { "examples": { "foo": { "value": "{\n \"versions\": [\n {\n \"status\": \"CURRENT\",\n \"updated\": \"2011-01-21T11:33:21Z\",\n \"id\": \"v2.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v2/\",\n \"rel\": \"self\"\n }\n ]\n },\n {\n \"status\": \"EXPERIMENTAL\",\n \"updated\": \"2013-07-23T11:33:21Z\",\n \"id\": \"v3.0\",\n \"links\": [\n {\n \"href\": \"http://127.0.0.1:8774/v3/\",\n \"rel\": \"self\"\n }\n ]\n }\n ]\n}\n" } } } } } } } }, "/v2": { "get": { "operationId": "getVersionDetailsv2", "summary": "Show API version details", "responses": { "200": { "description": "200 response", "content": { "application/json": { "examples": { "foo": { "value": { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } } } } } }, "203": { "description": "203 response", "content": { "application/json": { "examples": { "foo": { "value": { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://23.253.228.211:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } } } } } } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/api-with-examples.yaml000066400000000000000000000144541401301652500242570ustar00rootroot00000000000000openapi: "3.0.0" info: title: Simple API overview version: 2.0.0 paths: /: get: operationId: listVersionsv2 summary: List API versions responses: '200': description: |- 200 response content: application/json: examples: foo: value: { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self" } ] } ] } '300': description: |- 300 response content: application/json: examples: foo: value: | { "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" } ] }, { "status": "EXPERIMENTAL", "updated": "2013-07-23T11:33:21Z", "id": "v3.0", "links": [ { "href": "http://127.0.0.1:8774/v3/", "rel": "self" } ] } ] } /v2: get: operationId: getVersionDetailsv2 summary: Show API version details responses: '200': description: |- 200 response content: application/json: examples: foo: value: { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } '203': description: |- 203 response content: application/json: examples: foo: value: { "version": { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" }, { "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } ], "id": "v2.0", "links": [ { "href": "http://23.253.228.211:8774/v2/", "rel": "self" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf", "type": "application/pdf", "rel": "describedby" }, { "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl", "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } ] } } OpenAPI-Specification-3.1.0/examples/v3.0/callback-example.json000066400000000000000000000051501401301652500241060ustar00rootroot00000000000000{ "openapi": "3.0.0", "info": { "title": "Callback Example", "version": "1.0.0" }, "paths": { "/streams": { "post": { "description": "subscribes a client to receive out-of-band data", "parameters": [ { "name": "callbackUrl", "in": "query", "required": true, "description": "the location where data will be sent. Must be network accessible\nby the source server\n", "schema": { "type": "string", "format": "uri", "example": "https://tonys-server.com" } } ], "responses": { "201": { "description": "subscription successfully created", "content": { "application/json": { "schema": { "description": "subscription information", "required": [ "subscriptionId" ], "properties": { "subscriptionId": { "description": "this unique identifier allows management of the subscription", "type": "string", "example": "2531329f-fb09-4ef7-887e-84e648214436" } } } } } } }, "callbacks": { "onData": { "{$request.query.callbackUrl}/data": { "post": { "requestBody": { "description": "subscription payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "userData": { "type": "string" } } } } } }, "responses": { "202": { "description": "Your server implementation should return this HTTP status code\nif the data was received successfully\n" }, "204": { "description": "Your server should return this HTTP status code if no longer interested\nin further updates\n" } } } } } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/callback-example.yaml000066400000000000000000000041561401301652500241040ustar00rootroot00000000000000openapi: 3.0.0 info: title: Callback Example version: 1.0.0 paths: /streams: post: description: subscribes a client to receive out-of-band data parameters: - name: callbackUrl in: query required: true description: | the location where data will be sent. Must be network accessible by the source server schema: type: string format: uri example: https://tonys-server.com responses: '201': description: subscription successfully created content: application/json: schema: description: subscription information required: - subscriptionId properties: subscriptionId: description: this unique identifier allows management of the subscription type: string example: 2531329f-fb09-4ef7-887e-84e648214436 callbacks: # the name `onData` is a convenience locator onData: # when data is sent, it will be sent to the `callbackUrl` provided # when making the subscription PLUS the suffix `/data` '{$request.query.callbackUrl}/data': post: requestBody: description: subscription payload content: application/json: schema: type: object properties: timestamp: type: string format: date-time userData: type: string responses: '202': description: | Your server implementation should return this HTTP status code if the data was received successfully '204': description: | Your server should return this HTTP status code if no longer interested in further updates OpenAPI-Specification-3.1.0/examples/v3.0/link-example.json000066400000000000000000000171051401301652500233120ustar00rootroot00000000000000{ "openapi": "3.0.0", "info": { "title": "Link Example", "version": "1.0.0" }, "paths": { "/2.0/users/{username}": { "get": { "operationId": "getUserByName", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } }, "links": { "userRepositories": { "$ref": "#/components/links/UserRepositories" } } } } } }, "/2.0/repositories/{username}": { "get": { "operationId": "getRepositoriesByOwner", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "repositories owned by the supplied user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/repository" } } } }, "links": { "userRepository": { "$ref": "#/components/links/UserRepository" } } } } } }, "/2.0/repositories/{username}/{slug}": { "get": { "operationId": "getRepository", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The repository", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/repository" } } }, "links": { "repositoryPullRequests": { "$ref": "#/components/links/RepositoryPullRequests" } } } } } }, "/2.0/repositories/{username}/{slug}/pullrequests": { "get": { "operationId": "getPullRequestsByRepository", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "open", "merged", "declined" ] } } ], "responses": { "200": { "description": "an array of pull request objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pullrequest" } } } } } } } }, "/2.0/repositories/{username}/{slug}/pullrequests/{pid}": { "get": { "operationId": "getPullRequestsById", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "a pull request object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pullrequest" } } }, "links": { "pullRequestMerge": { "$ref": "#/components/links/PullRequestMerge" } } } } } }, "/2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge": { "post": { "operationId": "mergePullRequest", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "the PR was successfully merged" } } } } }, "components": { "links": { "UserRepositories": { "operationId": "getRepositoriesByOwner", "parameters": { "username": "$response.body#/username" } }, "UserRepository": { "operationId": "getRepository", "parameters": { "username": "$response.body#/owner/username", "slug": "$response.body#/slug" } }, "RepositoryPullRequests": { "operationId": "getPullRequestsByRepository", "parameters": { "username": "$response.body#/owner/username", "slug": "$response.body#/slug" } }, "PullRequestMerge": { "operationId": "mergePullRequest", "parameters": { "username": "$response.body#/author/username", "slug": "$response.body#/repository/slug", "pid": "$response.body#/id" } } }, "schemas": { "user": { "type": "object", "properties": { "username": { "type": "string" }, "uuid": { "type": "string" } } }, "repository": { "type": "object", "properties": { "slug": { "type": "string" }, "owner": { "$ref": "#/components/schemas/user" } } }, "pullrequest": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "repository": { "$ref": "#/components/schemas/repository" }, "author": { "$ref": "#/components/schemas/user" } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/link-example.yaml000066400000000000000000000122401401301652500232760ustar00rootroot00000000000000openapi: 3.0.0 info: title: Link Example version: 1.0.0 paths: /2.0/users/{username}: get: operationId: getUserByName parameters: - name: username in: path required: true schema: type: string responses: '200': description: The User content: application/json: schema: $ref: '#/components/schemas/user' links: userRepositories: $ref: '#/components/links/UserRepositories' /2.0/repositories/{username}: get: operationId: getRepositoriesByOwner parameters: - name: username in: path required: true schema: type: string responses: '200': description: repositories owned by the supplied user content: application/json: schema: type: array items: $ref: '#/components/schemas/repository' links: userRepository: $ref: '#/components/links/UserRepository' /2.0/repositories/{username}/{slug}: get: operationId: getRepository parameters: - name: username in: path required: true schema: type: string - name: slug in: path required: true schema: type: string responses: '200': description: The repository content: application/json: schema: $ref: '#/components/schemas/repository' links: repositoryPullRequests: $ref: '#/components/links/RepositoryPullRequests' /2.0/repositories/{username}/{slug}/pullrequests: get: operationId: getPullRequestsByRepository parameters: - name: username in: path required: true schema: type: string - name: slug in: path required: true schema: type: string - name: state in: query schema: type: string enum: - open - merged - declined responses: '200': description: an array of pull request objects content: application/json: schema: type: array items: $ref: '#/components/schemas/pullrequest' /2.0/repositories/{username}/{slug}/pullrequests/{pid}: get: operationId: getPullRequestsById parameters: - name: username in: path required: true schema: type: string - name: slug in: path required: true schema: type: string - name: pid in: path required: true schema: type: string responses: '200': description: a pull request object content: application/json: schema: $ref: '#/components/schemas/pullrequest' links: pullRequestMerge: $ref: '#/components/links/PullRequestMerge' /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: post: operationId: mergePullRequest parameters: - name: username in: path required: true schema: type: string - name: slug in: path required: true schema: type: string - name: pid in: path required: true schema: type: string responses: '204': description: the PR was successfully merged components: links: UserRepositories: # returns array of '#/components/schemas/repository' operationId: getRepositoriesByOwner parameters: username: $response.body#/username UserRepository: # returns '#/components/schemas/repository' operationId: getRepository parameters: username: $response.body#/owner/username slug: $response.body#/slug RepositoryPullRequests: # returns '#/components/schemas/pullrequest' operationId: getPullRequestsByRepository parameters: username: $response.body#/owner/username slug: $response.body#/slug PullRequestMerge: # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge operationId: mergePullRequest parameters: username: $response.body#/author/username slug: $response.body#/repository/slug pid: $response.body#/id schemas: user: type: object properties: username: type: string uuid: type: string repository: type: object properties: slug: type: string owner: $ref: '#/components/schemas/user' pullrequest: type: object properties: id: type: integer title: type: string repository: $ref: '#/components/schemas/repository' author: $ref: '#/components/schemas/user' OpenAPI-Specification-3.1.0/examples/v3.0/petstore-expanded.json000066400000000000000000000164141401301652500243610ustar00rootroot00000000000000{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "Swagger API Team", "email": "apiteam@swagger.io", "url": "http://swagger.io" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "http://petstore.swagger.io/api" } ], "paths": { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n", "operationId": "findPets", "parameters": [ { "name": "tags", "in": "query", "description": "tags to filter by", "required": false, "style": "form", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "in": "query", "description": "maximum number of results to return", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "pet response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "description": "Creates a new pet in the store. Duplicates are allowed", "operationId": "addPet", "requestBody": { "description": "Pet to add to the store", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPet" } } } }, "responses": { "200": { "description": "pet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pets/{id}": { "get": { "description": "Returns a user based on a single ID, if the user does not have access to the pet", "operationId": "find pet by id", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to fetch", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "pet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "description": "deletes a single pet based on the ID supplied", "operationId": "deletePet", "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to delete", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "204": { "description": "pet deleted" }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Pet": { "allOf": [ { "$ref": "#/components/schemas/NewPet" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "format": "int64" } } } ] }, "NewPet": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "tag": { "type": "string" } } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/petstore-expanded.yaml000066400000000000000000000125471401301652500243550ustar00rootroot00000000000000openapi: "3.0.0" info: version: 1.0.0 title: Swagger Petstore description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification termsOfService: http://swagger.io/terms/ contact: name: Swagger API Team email: apiteam@swagger.io url: http://swagger.io license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: http://petstore.swagger.io/api paths: /pets: get: description: | Returns all pets from the system that the user has access to Nam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia. Sed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien. operationId: findPets parameters: - name: tags in: query description: tags to filter by required: false style: form schema: type: array items: type: string - name: limit in: query description: maximum number of results to return required: false schema: type: integer format: int32 responses: '200': description: pet response content: application/json: schema: type: array items: $ref: '#/components/schemas/Pet' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: description: Creates a new pet in the store. Duplicates are allowed operationId: addPet requestBody: description: Pet to add to the store required: true content: application/json: schema: $ref: '#/components/schemas/NewPet' responses: '200': description: pet response content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /pets/{id}: get: description: Returns a user based on a single ID, if the user does not have access to the pet operationId: find pet by id parameters: - name: id in: path description: ID of pet to fetch required: true schema: type: integer format: int64 responses: '200': description: pet response content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: description: deletes a single pet based on the ID supplied operationId: deletePet parameters: - name: id in: path description: ID of pet to delete required: true schema: type: integer format: int64 responses: '204': description: pet deleted default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Pet: allOf: - $ref: '#/components/schemas/NewPet' - type: object required: - id properties: id: type: integer format: int64 NewPet: type: object required: - name properties: name: type: string tag: type: string Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string OpenAPI-Specification-3.1.0/examples/v3.0/petstore.json000066400000000000000000000075741401301652500226020ustar00rootroot00000000000000{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "license": { "name": "MIT" } }, "servers": [ { "url": "http://petstore.swagger.io/v1" } ], "paths": { "/pets": { "get": { "summary": "List all pets", "operationId": "listPets", "tags": [ "pets" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many items to return at one time (max 100)", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "A paged array of pets", "headers": { "x-next": { "description": "A link to the next page of responses", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pets" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a pet", "operationId": "createPets", "tags": [ "pets" ], "responses": { "201": { "description": "Null response" }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pets/{petId}": { "get": { "summary": "Info for a specific pet", "operationId": "showPetById", "tags": [ "pets" ], "parameters": [ { "name": "petId", "in": "path", "required": true, "description": "The id of the pet to retrieve", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expected response to a valid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Pet": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } }, "Pets": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/petstore.yaml000066400000000000000000000050151401301652500225570ustar00rootroot00000000000000openapi: "3.0.0" info: version: 1.0.0 title: Swagger Petstore license: name: MIT servers: - url: http://petstore.swagger.io/v1 paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer format: int32 responses: '200': description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: "#/components/schemas/Pets" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" post: summary: Create a pet operationId: createPets tags: - pets responses: '201': description: Null response default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" /pets/{petId}: get: summary: Info for a specific pet operationId: showPetById tags: - pets parameters: - name: petId in: path required: true description: The id of the pet to retrieve schema: type: string responses: '200': description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Pet" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error" components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string Pets: type: array items: $ref: "#/components/schemas/Pet" Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string OpenAPI-Specification-3.1.0/examples/v3.0/uspto.json000066400000000000000000000217421401301652500221000ustar00rootroot00000000000000{ "openapi": "3.0.1", "servers": [ { "url": "{scheme}://developer.uspto.gov/ds-api", "variables": { "scheme": { "description": "The Data Set API is accessible via https and http", "enum": [ "https", "http" ], "default": "https" } } } ], "info": { "description": "The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters.", "version": "1.0.0", "title": "USPTO Data Set API", "contact": { "name": "Open Data Portal", "url": "https://developer.uspto.gov", "email": "developer@uspto.gov" } }, "tags": [ { "name": "metadata", "description": "Find out about the data sets" }, { "name": "search", "description": "Search a data set" } ], "paths": { "/": { "get": { "tags": [ "metadata" ], "operationId": "list-data-sets", "summary": "List available data sets", "responses": { "200": { "description": "Returns a list of data sets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dataSetList" }, "example": { "total": 2, "apis": [ { "apiKey": "oa_citations", "apiVersionNumber": "v1", "apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json" }, { "apiKey": "cancer_moonshot", "apiVersionNumber": "v1", "apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json" } ] } } } } } } }, "/{dataset}/{version}/fields": { "get": { "tags": [ "metadata" ], "summary": "Provides the general information about the API and the list of fields that can be used to query the dataset.", "description": "This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below.", "operationId": "list-searchable-fields", "parameters": [ { "name": "dataset", "in": "path", "description": "Name of the dataset.", "required": true, "example": "oa_citations", "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "Version of the dataset.", "required": true, "example": "v1", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The dataset API for the given version is found and it is accessible to consume.", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "The combination of dataset name and version is not found in the system or it is not published yet to be consumed by public.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/{dataset}/{version}/records": { "post": { "tags": [ "search" ], "summary": "Provides search capability for the data set with the given search criteria.", "description": "This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api.", "operationId": "perform-search", "parameters": [ { "name": "version", "in": "path", "description": "Version of the dataset.", "required": true, "schema": { "type": "string", "default": "v1" } }, { "name": "dataset", "in": "path", "description": "Name of the dataset. In this case, the default value is oa_citations", "required": true, "schema": { "type": "string", "default": "oa_citations" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "object" } } } } } }, "404": { "description": "No matching record found for the given criteria." } }, "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "criteria": { "description": "Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values.", "type": "string", "default": "*:*" }, "start": { "description": "Starting record number. Default value is 0.", "type": "integer", "default": 0 }, "rows": { "description": "Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset.", "type": "integer", "default": 100 } }, "required": [ "criteria" ] } } } } } } }, "components": { "schemas": { "dataSetList": { "type": "object", "properties": { "total": { "type": "integer" }, "apis": { "type": "array", "items": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "To be used as a dataset parameter value" }, "apiVersionNumber": { "type": "string", "description": "To be used as a version parameter value" }, "apiUrl": { "type": "string", "format": "uriref", "description": "The URL describing the dataset's fields" }, "apiDocumentationUrl": { "type": "string", "format": "uriref", "description": "A URL to the API console for each API" } } } } } } } } }OpenAPI-Specification-3.1.0/examples/v3.0/uspto.yaml000066400000000000000000000170771401301652500220770ustar00rootroot00000000000000openapi: 3.0.1 servers: - url: '{scheme}://developer.uspto.gov/ds-api' variables: scheme: description: 'The Data Set API is accessible via https and http' enum: - 'https' - 'http' default: 'https' info: description: >- The Data Set API (DSAPI) allows the public users to discover and search USPTO exported data sets. This is a generic API that allows USPTO users to make any CSV based data files searchable through API. With the help of GET call, it returns the list of data fields that are searchable. With the help of POST call, data can be fetched based on the filters on the field names. Please note that POST call is used to search the actual data. The reason for the POST call is that it allows users to specify any complex search criteria without worry about the GET size limitations as well as encoding of the input parameters. version: 1.0.0 title: USPTO Data Set API contact: name: Open Data Portal url: 'https://developer.uspto.gov' email: developer@uspto.gov tags: - name: metadata description: Find out about the data sets - name: search description: Search a data set paths: /: get: tags: - metadata operationId: list-data-sets summary: List available data sets responses: '200': description: Returns a list of data sets content: application/json: schema: $ref: '#/components/schemas/dataSetList' example: { "total": 2, "apis": [ { "apiKey": "oa_citations", "apiVersionNumber": "v1", "apiUrl": "https://developer.uspto.gov/ds-api/oa_citations/v1/fields", "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/oa_citations.json" }, { "apiKey": "cancer_moonshot", "apiVersionNumber": "v1", "apiUrl": "https://developer.uspto.gov/ds-api/cancer_moonshot/v1/fields", "apiDocumentationUrl": "https://developer.uspto.gov/ds-api-docs/index.html?url=https://developer.uspto.gov/ds-api/swagger/docs/cancer_moonshot.json" } ] } /{dataset}/{version}/fields: get: tags: - metadata summary: >- Provides the general information about the API and the list of fields that can be used to query the dataset. description: >- This GET API returns the list of all the searchable field names that are in the oa_citations. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the syntax options shown below. operationId: list-searchable-fields parameters: - name: dataset in: path description: 'Name of the dataset.' required: true example: "oa_citations" schema: type: string - name: version in: path description: Version of the dataset. required: true example: "v1" schema: type: string responses: '200': description: >- The dataset API for the given version is found and it is accessible to consume. content: application/json: schema: type: string '404': description: >- The combination of dataset name and version is not found in the system or it is not published yet to be consumed by public. content: application/json: schema: type: string /{dataset}/{version}/records: post: tags: - search summary: >- Provides search capability for the data set with the given search criteria. description: >- This API is based on Solr/Lucene Search. The data is indexed using SOLR. This GET API returns the list of all the searchable field names that are in the Solr Index. Please see the 'fields' attribute which returns an array of field names. Each field or a combination of fields can be searched using the Solr/Lucene Syntax. Please refer https://lucene.apache.org/core/3_6_2/queryparsersyntax.html#Overview for the query syntax. List of field names that are searchable can be determined using above GET api. operationId: perform-search parameters: - name: version in: path description: Version of the dataset. required: true schema: type: string default: v1 - name: dataset in: path description: 'Name of the dataset. In this case, the default value is oa_citations' required: true schema: type: string default: oa_citations responses: '200': description: successful operation content: application/json: schema: type: array items: type: object additionalProperties: type: object '404': description: No matching record found for the given criteria. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: criteria: description: >- Uses Lucene Query Syntax in the format of propertyName:value, propertyName:[num1 TO num2] and date range format: propertyName:[yyyyMMdd TO yyyyMMdd]. In the response please see the 'docs' element which has the list of record objects. Each record structure would consist of all the fields and their corresponding values. type: string default: '*:*' start: description: Starting record number. Default value is 0. type: integer default: 0 rows: description: >- Specify number of rows to be returned. If you run the search with default values, in the response you will see 'numFound' attribute which will tell the number of records available in the dataset. type: integer default: 100 required: - criteria components: schemas: dataSetList: type: object properties: total: type: integer apis: type: array items: type: object properties: apiKey: type: string description: To be used as a dataset parameter value apiVersionNumber: type: string description: To be used as a version parameter value apiUrl: type: string format: uriref description: "The URL describing the dataset's fields" apiDocumentationUrl: type: string format: uriref description: A URL to the API console for each API OpenAPI-Specification-3.1.0/examples/v3.1/000077500000000000000000000000001401301652500200265ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/examples/v3.1/webhook-example.json000066400000000000000000000017411401301652500240130ustar00rootroot00000000000000{ "openapi": "3.1.0", "info": { "title": "Webhook Example", "version": "1.0.0" }, "webhooks": { "newPet": { "post": { "requestBody": { "description": "Information about a new pet in the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } } } } }, "components": { "schemas": { "Pet": { "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } } } }OpenAPI-Specification-3.1.0/examples/v3.1/webhook-example.yaml000066400000000000000000000016421401301652500240040ustar00rootroot00000000000000openapi: 3.1.0 info: title: Webhook Example version: 1.0.0 # Since OAS 3.1.0 the paths element isn't necessary. Now a valid OpenAPI Document can describe only paths, webhooks, or even only reusable components webhooks: # Each webhook needs a name newPet: # This is a Path Item Object, the only difference is that the request is initiated by the API provider post: requestBody: description: Information about a new pet in the system content: application/json: schema: $ref: "#/components/schemas/Pet" responses: "200": description: Return a 200 status to indicate that the data was received successfully components: schemas: Pet: required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string OpenAPI-Specification-3.1.0/guidelines/000077500000000000000000000000001401301652500176515ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/guidelines/EXTENSIONS.md000066400000000000000000000001331401301652500216670ustar00rootroot00000000000000For OpenAPI Specification version 2.0, please see [v2.0/EXTENSIONS.md](v2.0/EXTENSIONS.md) OpenAPI-Specification-3.1.0/guidelines/v2.0/000077500000000000000000000000001401301652500203365ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/guidelines/v2.0/EXTENSIONS.md000066400000000000000000000062371401301652500223670ustar00rootroot00000000000000# OpenAPI Extensions The OpenAPI Specification version 2.0 allows for custom properties to be added at several places within an OpenAPI document., allowing API providers to extend the meta-data provided for their REST APIs as needed. Extension properties are always prefixed by "x-" and can have any valid JSON format value. Currently extension properties are supported in the following definition objects: * within the [info object](/versions/2.0.md#info-object) * within the [paths object](/versions/2.0.md#paths-object) * within the [path-item object](/versions/2.0.md#path-item-object) * within the [operation object](/versions/2.0.md#operationObject) * within the [parameter object](/versions/2.0.md#parameterObject) * within the [responses object](/versions/2.0.md#responses-object) * within the [tag object](/versions/2.0.md#tag-object) * within the [security-scheme object](/versions/2.0.md#security-scheme-object) For example, a vendor extension that adds apis.json specific metadata to an OpenAPI definition might look as follows: ```json { "swagger": "2.0", "info": { "version": "1.0", "title": "Analysis", "description" : "Provides access to blog posts and analysis across the API Evangelist network.", "x-apis-json" : { "image": "https://s3.amazonaws.com/kinlane-productions/api-evangelist/t-shirts/KL_InApiWeTrust-1000.png", "humanURL": "http://developer.apievangelist.com", "baseURL": "http://api.apievangelist.com/definitions/Analysis", "tags": [ "blog", "industry", "analysis", "new", "API", "Application Programming Interface" ], "properties": [ { "type": "X-signup", "url": "https://apievangelist.3scale.net/" }, { "type": "X-blog", "url": "http://developer.apievangelist.com/blog/" }, { "type": "X-apicommonsmanifest", "url": "https://raw.githubusercontent.com/kinlane/analysis-api/master/api-commons-manifest.json" } ], } }, "basePath": "/", "paths": { ... } } ``` This could be used by corresponding tooling that builds apis.json files for OpenAPI definitions, the advantage being that all metadata for the API is within one definition instead of spread out amongst multiple files. Another (simplified) example could be how to specify a [JWE encryption](http://hdknr.github.io/docs/identity/jwe.html) policy to parameters, for example as follows: ```json { ... "socialSecurityNumber": { "name": "socialSecurityNumber", "in": "query", "description": "a social security number", "required": false, "type": "string", "x-jwe-encryption" : { "algorithm" : "RSA-OAEP", "encryption" : "A256GCM" } } } ... } ``` An API consumer reading these parameter definitions could interpret this as having to encrypt the skip parameter in line with the JWE standard. ## Annotations The OpenAPI-specific annotations currently available for jax-rs APIs do not support the addition of extension data. OpenAPI-Specification-3.1.0/guidelines/v2.0/README.md000066400000000000000000000002301401301652500216100ustar00rootroot00000000000000## Guidelines for OpenAPI Definitions * [Reuse](REUSE.md) of OpenAPI definitions * [Extending](EXTENSIONS.md) OpenAPI definitions with custom metadata OpenAPI-Specification-3.1.0/guidelines/v2.0/REUSE.md000066400000000000000000000226161401301652500215520ustar00rootroot00000000000000# Reuse Philosophy We encourage reuse and patterns through references. ## What is reusable The following types are reusable, as defined by the spec: * Parameters * Models (_or Schema Objects in general_) * Responses * Operations (_Operations can only be remote references_) ## Reuse strategy When authoring API design documents, common object definitions can be utilized to avoid duplication. For example, imagine multiple path definitions that each share a common path parameter, or a common response structure. The OpenAPI specification allows reuse of common object definitions through the use of "references". A reference is a construct in your API design document that indicates "the content for this portion of the document is defined elsewhere". To create a reference, at the location in your document where you want to reuse some other definition, create an object that has a `$ref` property whose value is a URI pointing to where the definition is (more on this in later sections). OpenAPI's provides reference capabilities using the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification. ### JSON Example ``` js { // ... definitions: { Person: { type: 'object', properties: { friends: { type: 'array', items: { $ref: '#/definitions/Person' } } } } } } ``` ### YAML Example ``` yaml # ... definitions: Person: type: object properties: friends: type: array items: $ref: '#/definitions/Person' ``` Note: YAML has a very similar feature, [YAML anchors](http://yaml.org/spec/1.2/spec.html#id2765878). Examples from this point will only be in JSON, using JSON References. ## Techniques ### Guidelines for Referencing All references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification. JSON Reference provides guidance on the resolution of references, notably: > If the URI contained in the JSON Reference value is a relative URI, then the base URI resolution MUST be calculated according to [RFC3986], section 5.2. Resolution is performed relative to the referring document. Whether you reference definitions locally or remote, you can never override or change their definitions from the referring location. The definitions can only be used as-is. #### Local references When referencing locally (within the current document), the target references should follow the conventions, as defined by the spec: * Parameters -> `#/parameters` * Responses -> `#/responses` * Definitions (Models/Schema) -> `#/definitions` An example of a local definition reference: _Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_ ``` json // ... "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } ``` #### Remote references ##### Relative path Files can be referred to in relative paths to the current document. _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... "responses": { "default": { "description": "unexpected error", "schema": { "$ref": "../common/Error.json" } } } ``` Remote references may also reference properties within the relative remote file. _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... "parameters": [ { "$ref": "parameters.json#/tagsParam" }, { "$ref": "parameters.json#/limitsParam" } ] ``` ##### URL Remote files can be hosted on an HTTP server (rather than the local file system). One risk of this approach is that environment specific issues could arise if DNS is not taken into account (as the reference can only contain one hostname). _Assuming file https://my.company.com/definitions/Model.json_ ```json { "description": "A simple model", "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "tag": { "description": "A complex, shared property. Note the absolute reference", "$ref": "https://my.company.com/definitions/Tag.json" } } } ``` Remote references may also reference properties within the remote file. _Assuming file https://my.company.com/definitions/models.json_ ```json { "models": { "Model": { "description": "A simple model", "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "tag": { "description": "a complex, shared property. Note the absolute reference", "$ref": "https://my.company.com/definitions/models.json#/models/Tag" } } }, "Tag": { "description": "A tag entity in the system", "type": "object", "properties": { "name": { "type": "string" } } } } } ``` ### Definitions Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization. Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. ### Parameters Similar to model schemas, you can create a repository of `parameters` to describe the common entities that appear throughout a set of systems. Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. Using the same technique as above, you can host on either a single or multiple files. For simplicity, the example below assumes a single file. _Assuming file https://my.company.com/parameters/parameters.json_ ```json { "query" : { "skip": { "name": "skip", "in": "query", "description": "Results to skip when paginating through a result set", "required": false, "minimum": 0, "type": "integer", "format": "int32" }, "limit": { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "minimum": 0, "type": "integer", "format": "int32" } } } ``` To include these parameters, you would need to add them individually as such: ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "produces": [ "application/json" ], "responses": { "200": { "description": "A list of pets.", "parameters" : [ { "$ref": "https://my.company.com/parameters/parameters.json#/query/skip" }, { "$ref": "https://my.company.com/parameters/parameters.json#/query/limit" }, { "in": "query", "name": "type", "description": "the types of pet to return", "required": false, "type": "string" } ], "schema": { "type": "array", "items": { "$ref": "#/definitions/pet" } } } } } } } ``` ### Operations Again, Operations can be shared across files. Although the reusability of operations will be less than with Parameters and Definitions. For this example, we will share a common `health` resource so that all APIs can reference it: Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. ```json { "/health": { "$ref": "http://localhost:8000/operations.json#/health" } } ``` Which points to the reference in the `operations.json` file: ```json { "health": { "get": { "tags": [ "admin" ], "summary": "Returns server health information", "operationId": "getHealth", "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "Health information from the server", "schema": { "$ref": "http://localhost:8000/models.json#/Health" } } } } } } ``` Remember, you cannot override the definitions, but in this case, you can add additional operations on the same path level. ### Responses Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies. Assume the file `responses.json`: ```json { "NotFoundError": { "description": "Entity not found", "schema": { "$ref": "#/definitions/ErrorModel" } } } ``` You can refer to it from a response definition: ```json { "/pets/{petId}": { "get": { "tags": [ "pet" ], "summary": "Returns server health information", "operationId": "getHealth", "produces": [ "application/json" ], "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet to return", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "The pet", "schema": { "$ref": "#/definitions/Pet" } }, "400": { "$ref": "http://localhost:8000/responses.json#/NotFoundError" } } } } } ``` OpenAPI-Specification-3.1.0/package.json000066400000000000000000000011571401301652500200130ustar00rootroot00000000000000{ "name": "oas-schemas", "version": "2.0.0", "description": "OpenAPI Specification JSON schemas", "author": { "name": "OpenAPI Initiative TSC", "email": "tsc@openapis.org", "url": "https://openapis.org/" }, "repository": { "type": "git", "url": "https://github.com/OAI/OpenAPI-Specification.git" }, "license": "Apache-2.0", "readmeFilename": "README.md", "files": [ "README.md", "schemas/*" ], "dependencies": {}, "devDependencies": { "mdv": "^1.0.7", "yaml": "^1.8.3" }, "keywords": [ "OpenAPI", "OAS", "Swagger", "schema", "API" ] } OpenAPI-Specification-3.1.0/proposals/000077500000000000000000000000001401301652500175435ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/proposals/000_OAS-proposal-template.md000066400000000000000000000043321401301652500245360ustar00rootroot00000000000000# Feature name ## Metadata |Tag |Value | |---- | ---------------- | |Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| |Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})| |Review Manager |TBD | |Status |Proposal, Draft, Promoted, or Abandoned| |Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)| |Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})| |Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) | ## Change Log |Date |Responsible Party |Description | |---- | ---------------- | ---------- | ## Introduction A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. ## Motivation Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code. ## Proposed solution Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? ## Detailed design Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section. ## Backwards compatibility Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed. ## Alternatives considered Describe alternative approaches to addressing the same problem, and why you chose this approach instead. OpenAPI-Specification-3.1.0/proposals/001_Alternative Schema Proposal.md000066400000000000000000000076711401301652500256770ustar00rootroot00000000000000# Alternative Schema ## Metadata |Tag |Value | |---- | ---------------- | |Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| |Authors|[Chuck Heazel](https://github.com/{cmheazel})| |Review Manager |TBD | |Status |**Draft** | |Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md) |Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)| |Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) | .Change Log |Date |Responsible Party |Description | |---- | ---------------- | ---------- | |3/15/19 |C. Heazel|Initial Markup Draft | |4/17/19 |C. Heazel|Re-structured based on Apple Swift| ## Introduction This a proposal to add a new field called ``alternativeSchema`` to the OAS. ## Motivation OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used. For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be. ## Proposed solution This proposal makes the following changes to the OAS 3.0 specification: 1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field. 1. Addition of the Alternative Schema Object. 1. Addition of Alternative Schema examples. 1. Addition of a preliminary discussion of the Alternative Schema registry. ## Detailed design ### Extend the Schema Object The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md) ### Add the Alternative Schema Object The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md) ### Provide Alternative Schema Examples Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md) ### Alternative Schema Registry Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at . *** Note this is a placeholder registry. Don't take the values seriously. *** Inital contents of the registry will include: |Name |Link |Description | |--- | --- | --- | |jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema | ## Backwards compatibility This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly. ## Alternatives considered Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language. OpenAPI-Specification-3.1.0/proposals/002_Webhooks.md000066400000000000000000000251061401301652500222330ustar00rootroot00000000000000# Webhooks ## Metadata |Tag |Value | |---- | ---------------- | |Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)| |Authors|[Lorna Mitchell](https://github.com/lornajane)| |Review Manager |TBD | |Status |Proposal| |Issues |[#1968](https://github.com/OAI/OpenAPI-Specification/issues/1968)| ## Change Log |Date |Responsible Party |Description | |---- | ---------------- | ---------- | | 17th July 2019 | Lorna Mitchell | Initial draft | ## Introduction Modern APIs often consist of two-way API traffic, but OpenAPI currently only supports some types of requests. Standard client-to-server API calls are well supported. Server-to-client callbacks are only supported if they are the result of an earlier API call and are documented by nesting under the path of that earlier call. Incoming HTTP reqests ("webhooks") cannot be described in the current version of OpenAPI if they are the result of subscription arranged outside of the scope of the API (e.g. by setting a callback URL in a web interface). ## Motivation OpenAPI supports a `callback` element, where the result of an API call is delivered at some later time as an incoming HTTP request to a nominated URL. However it does not support webhooks, where events arrive as an incoming HTTP request but the configuration of these requests was arranged outside of the scope of the API, e.g. on a website. For example: at Nexmo we have an SMS API (the docs are here: and the source spec here: ). It supports: * sending an SMS (an outgoing API call, currently supported) * receiving a delivery receipt when you just sent an SMS (callback, currently supported) * receiving an incoming SMS (webhook, not currently supported) The docs have an `x-webhooks` top-level element (we use [our own docs renderer](https://github.com/Nexmo/nexmo-oas-renderer)) and then a meaningless URL fieldname before the path item object that descrives the webhook. On one of the other Nexmo APIs, we simply documented our webhooks in a markdown file separate from our API even though the two directions are very closely linked (see [Voice API webhook reference](https://developer.nexmo.com/voice/voice-api/webhook-reference) ). Neither solution is great. I'm aware of other organisations (Ebay, GitHub) who also offer webhooks as part of their API platform who have run into the same problems when looking to adopt OpenAPI. The existing approach for callbacks, which allow a Path Item Object to be described in another location, could be adapted to also describe webhooks. ## Proposed solution Allow a top-level `webhooks` element, with named entries inside it, each containing a Path Item Object. No other new fields or changes would be needed, since this already works brilliantly for `callbacks` within a path item. The only difference here is that there's no existing path item for the callback/webhook to belong to, and the URL is usually set somewhere else by the user (and there's no request context for an expression to be evaluated). This solution builds on the existing proven approach for callbacks, but detaches them from the following-a-previous-API-call constraint. To borrow the Nexmo SMS API example from above (because it's simple, I can add more examples as needed), the spec for the incoming webhook that occurs because a message has arrived might look like this: ``` webhooks: inbound-sms: post: summary: Inbound SMS to your Nexmo number operationId: inbound-sms description: | If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your [webhook endpoint](https://developer.nexmo.com/concepts/guides/webhooks). requestBody: required: true content: application/json: schema: type: object required: - msisdn - to - messageid - text - type - keyword - message-timestamp properties: msisdn: type: string description: the phone number that this inbound message was sent from. numbers are specified in e.164 format. example: '447700900001' to: type: string description: the phone number the message was sent to. **this is your virtual number**. numbers are specified in e.164 format. example: '447700900000' messageid: type: string description: the id of the message example: 0a0000000123abcd1 text: type: string description: The message body for this inbound message. example: Hello world type: type: string description: | Possible values are: - `text` - standard text. - `unicode` - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on. - `binary` - a binary message. example: 'text' keyword: type: string description: The first word in the message body. This is typically used with short codes. example: Hello message-timestamp: description: The time when Nexmo started to push this Delivery Receipt to your webhook endpoint. type: string example: 2020-01-01 12:00:00 responses: '200': description: | Your server returns this code if it accepts the callback. Note that Nexmo will retry messages that are not successfully acknowledged. ``` ## Detailed design ### Add the `webhooks` top-level element to the list **Existing Spec:** ``` #### OpenAPI Object This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). ``` **Change: Add to the end of the table** ``` webhooks | [[Webhooks Object](#webhooksObject)] | The incoming webhooks that may be received as part of this API. ``` ### Describe a new Webhook Object (new spec section) ``` #### Webhooks Object A map of webhooks that may be received as incoming HTTP requests as part of the API. The key of the map is a unique short name for the webhook e.g. `messageEvent`. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. Webhook Objects differ from [Callback Objects](#callbackObject) in that the webhooks are the result of some external event, not an earlier API call to subscribe or cause some other effect. ##### Webhook Object Example The following example shows an incoming webhook delivering a status update for a particular item ID: ````yaml webhooks: statusUpdate: requestBody: description: Status updates on an item. You can set the URL for these updates in your example.com dashboard. content: 'application/json': schema: type: object required: - item_id - status properties: item_id: type: string description: The ID of the item example: 0a000000012345678 status: type: integer description: The status of this message, zero for success example: 14 responses: '200': description: webhook successfully processed and no retries will be performed ``` ## Backwards compatibility Adding a new top-level entry is not something to take lightly, however hopefully most tools will simply ignore what they weren't expecting and continue to operate on the parts of the spec they do understand until their functionality catches up with the spec change. ## Alternatives considered Another option is to add a special `path` that could contain the various webhooks using the exisiting `callback` syntax but existing tools which aren't expecting this special value may not handle it well, so this option was discounted. OpenAPI-Specification-3.1.0/proposals/003_Clarify-Nullable.md000066400000000000000000000403171401301652500236010ustar00rootroot00000000000000# Clarify Semantics of `nullable` in OpenAPI 3.0 ## Metadata |Tag |Value | |---- | ---------------- | |Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/003_Clarify-Nullable.md)| |Authors|[Ted Epstein](https://github.com/tedepstein)| |Review Manager |TBD| |Status |Proposal| |Implementations |N/A| |Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957), [2057](https://github.com/OAI/OpenAPI-Specification/issues/2057)| |Previous Revisions |N/A | ## Change Log |Date |Responsible Party |Description | |---- | ---------------- |------------| |Oct 31, 2019 | Ted Epstein | Initial proposal | ## Introduction This proposal aims to clarify the semantics of the `nullable` keyword in OpenAPI 3.0. This clarification would resolve ambiguities, reinforce the intended alignment with JSON Schema, and provide guidance for schema validators, translators, and other tools. ## Motivation The documentation of the `nullable` keyword is incomplete and ambiguous, leaving many questions unanswered, and causing significant difficulty in reconciling certain assumed semantics with JSON Schema. To summarize the problems: * `nullable: true` is an _expanding assertion_ that doesn't fit JSON Schema's constraint-based processing model. It is not clear how it interacts with other keywords, and within what scope. * `nullable: false`, which is the default value, is not clearly defined, and could be interpreted in a way that breaks fundamental assumptions of JSON Schema. * Different OpenAPI schema validators and other tool implementations are likely to have different behaviors because the semantics of `nullable` are not fully specified. * Because of the above ambiguities, it is not clear how to translate an OpenAPI Schema Object into a standard JSON Schema for message validation and for other purposes. Some possible interpretations of the OpenAPI spec could make translating to JSON Schema much more difficult. * Depending on the interpretation, `nullable` might interact with `oneOf` and `anyOf` in problematic and counter-intuitive ways. The solution proposed herein should: * Clarify the boundaries around `nullable` so we know how it interacts with other assertions, applicators, subtypes and supertypes within its context. * Clarify the meaning of `nullable: false`. * Reaffirm the intended alignment of OpenAPI's Schema Object with JSON Schema, and reconcile `nullable` with JSON Schema semantics. * Allow a straightforward translation from `nullable` in OpenAPI to type arrays in JSON Schema. Further details follow. ### Primary Use Case for `nullable` A Schema Object allows values of any data type, unless the type is restricted by the `type` keyword. The `type` keyword restricts the schema to a single data type, which can be `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"`, or `"object"`, but cannot be `"null"`. Some APIs restrict values to a single data type, but also allow explicit null values. OpenAPI Schema Objects can allow explicit null values by combining the `type` and `nullable` keywords. A `nullable` value of `true` modifies a typed schema to allow non-null values of a given type, and also allow `null`. This was the envisioned use case, and the primary motivation for introducing `nullable` into the OpenAPI 3.0 spec. There may be other possible usage scenarios or consequences of the `nullable` keyword, the way it is specified, or the way in which the spec may be interpreted or implemented. In our view, these other scenarios should be considered side effects or oversights. To the best of our knowledge, the `nullable` keyword was not intended for any purpose other than to allow `null` in a typed schema. ### Expanding vs. Constraining Assertions `nullable: true` is an _expanding assertion_, meaning it has the effect of expanding the range of acceptable values. By contrast, JSON Schema's central operating principle is constraint-based, where _constraining assertions_ are cumulative, immutable, and each constraint has veto power to disallow some range of values. The semantics of constraining assertions are well-defined by JSON Schema and implemented in many JSON Schema validators and other tools. But JSON Schema doesn't have expanding assertions, so those well-defined semantics don't apply to `nullable`. To address this, we need to translate `nullable: true` into a constraining assertion. Otherwise, we would have to specify in detail how `nullable` interacts with constraining assertions like `enum` and with boolean applicators like `allOf` and `anyOf`. ### Interpretation of `nullable: false` The documentation specifies that `nullable: false` is the default, but doesn't clearly state what that means. One reasonable interpretation suggests that null values are disallowed unless `nullable` is explicitly set to `true`. This breaks a fundamental rule of JSON Schema, which states that an empty object `{}` is a valid schema that permits all values, with no constraints. Breaking that rule takes OpenAPI's Schema Object even further out of alignment with JSON Schema's processing model. For example, if null values are disallowed by default, does the following `UTCDate` schema accept `null`? ```yaml components: schemas: OptionalDate: type: string format: date nullable: true UTCDate: allOf: - $ref: "#/components/schemas/OptionalDate" not: type: string pattern: "^.*Z.*$" ``` `UTCDate` does not specify a type of its own, and does not directly specify `nullable: true`. So if `null` is disallowed by default, even for untyped schemas, then `UTCDate` won't accept nulls. If we want it to accept nulls, we have to repeat `nullable: true` in `UTCDate`. This is not at all intuitive for API designers, and it breaks with JSON Schema's rule that any value is allowed unless it's explicitly disallowed. On the other hand, we could say that `UTCDate` inherits `nullable: true` from `OptionalDate`, therefore null values are allowed. But this kind of inheritance logic is completely foreign to JSON Schema. So this behavior is also counterintuitive, though for a different reason. It's also difficult to implement. Any JSON Schema validator would need to be hacked in highly disruptive ways to retrofit this behavior. Or a preprocessor would have to be introduced to propagate the effect of `nullable: true` through the `*Of` inheritance hierarchy. Whichever semantics we choose, it gets very messy. ### A closer look at `nullable: false` In fact, the OpenAPI 3.0 specification doesn't explicitly say that untyped schemas disallow null values. Here are the relevant parts: #### Data Types > Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00. To say that null is "not supported _as a type_" would definitely disallow `type: "null"` in a schema object. But it doesn't necessarily mean that an untyped schema disallows _null values_. #### Definition of `nullable` > Allows sending a null value for the defined schema. Default value is false. This uses the word "allows," but there's no mention of "disallows." To say that `nullable: true` _allows_ null where it would otherwise be prohibited, doesn't necessarily mean that `nullable: false` _disallows_ null where it would otherwise be allowed. `nullable: true` _modifies_ a typed schema by adding null to the allowed types. `nullable: false` could mean "no null values allowed" or it could just mean "no modification to the specified type assertion, if any." #### Schema Object > The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. > > type - Value MUST be a string. Multiple types via an array are not supported. There is no specified adjustment to the `type` property that disallows null values. So it should defer to the JSON Schema specification, which says that, in the absence of a `type` assertion, any valid JSON value is allowed. So the 3.0 spec is ambiguous about null values. It's not clear whether the spec intended to disallow null values by default, even in untyped schemas. This looks more like an accidental oversight, or an unfortunate choice of words, than a clear intention. ### Specific Questions Questions that are not answered by the current specification include the following: * If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).) * Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema? * Can `allOf` be used to define a nullable subtype of a non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).) * Can `allOf` be used to define a non-nullable subtype of a nullable base schema? * What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema? * Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).) ## Proposed solution We propose to clarify the 3.0 specification in the next patch release, to resolve these questions and align OpenAPI's Schema Object with JSON Schema's well-defined, constraint-based semantics. In our view, and consistent with the original intent, `nullable` should have a very limited, well-defined scope. It should satisfy the primary use case, i.e. allowing `null` in a typed schema, with minimal side effects. This is the proposed replacement for the `nullable` definition:
Field Name | Type | Description ---|:---:|--- nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`.
## Detailed design According to the above specification, `nullable` only operates within a narrow scope, wherein its translation to JSON Schema is straightforward: * `nullable` is only meaningful if its value is `true`. * `nullable: true` is only meaningful in combination with a `type` assertion specified in the same Schema Object. `nullable` acts as a `type` modifier, allowing `null` in addition to the specified type. * `nullable: true` operates within a single Schema Object. It does not "override" or otherwise compete with supertype or subtype schemas defined with `allOf` or other applicators. It cannot be directly "inherited" through those applicators, and it cannot be applied to an inherited `type` constraint. This also solves the issues of alignment with JSON Schema: * Since `type` is a constraint, JSON Schema's constraint-based processing model is fully applicable. Interactions between `type` and other constraining assertions and applicators are unambiguous, with each constraint having independent veto power. * It is now clear that `nullable: false`, whether explicit or by default, _does not_ prohibit null values. Consistent with JSON Schema, an empty object allows all values, including `null`. ### Questions Answered Following are answers to the questions posed above, assuming the proposed clarification is adopted: #### If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).) No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`. While the modified `type` now allows `null`, the `enum` does not. Consistent with JSON schema, a value conforms to the schema only if it is valid against _all_ constraints. Any constraint, in this case `enum`, can cause a value to fail validation, even if that value meets all of the other constraints. #### Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema? Yes, an untyped schema allows null values, in addition to all other types. `nullable: true` has no effect, because null values are already allowed. And `nullable: false` has no effect because it just leaves the `type` constraint unmodified. #### Can `allOf` be used to define a nullable subtype of a non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).) No. Subtypes can add constraints, but not relax them. #### Can `allOf` be used to define a non-nullable subtype of a nullable base schema? Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`. #### What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema? A nullable type should translate into a type array with two string elements: the name of the type specified in the Schema Object, and `"null"`. #### Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).) Yes. For example, a Schema Object with `"type" : "string", "nullable" : true` would translate to a JSON Schema with `"type" : ["string", "null"]`. That schema permits `"default" : null`, even with the [strict typing rule](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#properties) specified by OpenAPI 3.0: > default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`. ## Backwards compatibility Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations. With the clarification of `nullable: false`, we think the risk of actual breakage is miniscule, because the current ambiguity only affects untyped Schema Objects, which by their nature leave a lot of room for unexpected values. Any implementation that relies on schema validation to prevent null values should use explicitly typed schemas, and typed schemas unambiguously disallow `null` unless `nullable` is `true`. There might be a somewhat greater risk of breakage by specifying the effect of `nullable: true` as a `type` modifier. A more heavy-handed interpretation of `nullable: true`, [described here](https://github.com/OAI/OpenAPI-Specification/issues/1900#issuecomment-486772917), would make it equivalent to `anyOf [s, {type: "null"}]` where `s` is the schema as specified (excluding `nullable`). This would allow nulls even where they would be prohibited by other schema keywords, like `enum`. But this interpretation introduces far greater complexity than the narrowly scoped `type` modifier. We are not aware of any OpenAPI schema validator that actually attempts this, and there is nothing in the OpenAPI spec that says `nullable` can override constraining assertions. ## Alternatives considered [Pull request #1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957) has some history of other approaches considered along the way. The first attempt assumed that `nullable: false` would prohibit null values, and attempted to work around this while maintaining backward compatibility. On closer inspection, the specification does not say anything about `null` values being disallowed. So we believe our interpretation is correct, and highly advantageous in its alignment with JSON Schema. OpenAPI-Specification-3.1.0/proposals/004_Overlays.md000066400000000000000000000213051401301652500222550ustar00rootroot00000000000000# Overlays ## Metadata |Tag |Value | |---- | ---------------- | |Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| |Authors|[Darrel Miller](https://github.com/darrelmiller)| |Status |Proposal| |Issues |[1442](https://github.com/OAI/OpenAPI-Specification/issues/1442) [1722](https://github.com/OAI/OpenAPI-Specification/issues/1722)| ## Change Log |Date |Responsible Party |Description | |---- | ---------------- | ---------- | | 24th December 2019 | Darrel Miller | Initial draft | | 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.| ## Introduction In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date. #### Overlay Document An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. #### Overlay Object This is the root object of the [OpenAPI Overlay document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- overlay | `string` | Version of the Overlay specification that this document conforms to. info | [[Info Object](#overlayInfoObject)] | Identifying information about the overlay. extends | `url` | URL to an OpenAPI document this overlay applies to. updates | [[Update Object](#updateObject)] | A list of update objects to be applied to the target document. The list of update objects MUST be applied in sequential order to ensure a consistent outcome. Updates are applied to the result of the previous updates. This enables objects to be deleted in one update and then re-created in a subsequent update. The `extends` property can be used to indicate that the Overlay was designed to update a specific OpenAPI description. This is an optional property. Where no `extends` is provided it is the responsibility of tooling to apply the Overlay documents to the appropriate OpenAPI description. #### Info Object This object contains identifying information about the [OpenAPI Overlay document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | A human readable description of the purpose of the overlay. version | `string` | A version identifer for indicating changes to an overlay document. #### Update Object This object represents one or more changes to be applied to the target document at the location defined by the target JMESPath. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- target | `string` | A JMESPath expression referencing the target objects in the target document. value | [Any](#valueObject) | An object with the properties and values to be updated in the target document. Property has no impact if `remove` property is `true`. remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false. The properties of the `Value Object` MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the `Value Object` replace properties in the target object with the same name and new properties are appended to the target object. ##### Structured Overlays Example When updating properties throughout the target document it may be more efficient to create a single `Update Object` that mirrors the structure of the target document. e.g. ```yaml overlay: 1.0.0 info: title: Structured Overlay version: 1.0.0 updates: - target: "@" value: info: x-overlay-applied: structured-overlay paths: "/": summary: "The root resource" get: summary: "Retrieve the root resource" x-rate-limit: 100 "/pets": get: summary: "Retrieve a list of pets" x-rate-limit: 100 components: tags: ``` ##### Targeted Overlays Alternatively, where only a small number of updates need to be applied to a large document, each [Update Object](#updateObject) can be more targeted. ```yaml overlay: 1.0.0 info: title: Structured Overlay version: 1.0.0 updates: - target: paths."/foo".get value: description: This is the new description - target: paths."/bar".get value: description: This is the updated description - target: paths."/bar" value: post: description: This is an updated description of a child object x-safe: false ``` ##### Wildcard Overlays Examples One significant advantage of using the JMESPath syntax that it allows referencing multiple nodes in the target document. This would allow a single update object to be applied to multiple target objects using wildcards. ```yaml overlay: 1.0.0 info: title: Update many objects at once version: 1.0.0 updates: - target: paths.*.get value: x-safe: true - target: paths.*.get.parameters[?name=='filter' && in=='query'] value: schema: $ref: "/components/schemas/filterSchema" ``` ##### Array Modification Examples Due to the fact that we can now reference specific elements of the parameter array, it allows adding parameters. Parameters can be deleted using the `remove` property. Use of indexes to remove array items should be avoided where possible as indexes will change when items are removed. ```yaml overlay: 1.0.0 info: title: Add an array element version: 1.0.0 updates: - target: paths.*.get.parameters[length(@)] value: name: newParam in: query ``` ```yaml overlay: 1.0.0 info: title: Remove a array element version: 1.0.0 updates: - target: $.paths[*].get.parameters[? name == 'dummy'] remove: true ``` ## Proposal Summary ### Benefits - This approach addresses the two distinct approaches of structured overlay vs targeted overlay which suits distinct but equally valid scenarios. - Addresses the problem of modifying the parameters array and removes the need to replace the entire array when a small change is required. - Allows sets of related overlays to be stored in a same file. - Enables updating a set of objects based on a pattern. This might be an effective way of apply common behaviour across many operations in an API. ### Challenges - Tooling will need a JMESPath implementation. - Large overlays may be slow to process. - Multiple complex pattern based overlays may cause overlapping updates causing confusing outcomes. ## Alternatives considered JMESPath was chosen over JSONPath due to the fact that JMESPath has a [specification](http://jmespath.org/specification.html) and a set of test cases. This will help to ensure compatibility between implementations. ## Backwards compatibility Overlays will be described in a new specification that can be used alongside an OpenAPI Description, therefore there will be no compatibility issues for the initial release. Overlay documents can be used against OpenAPI v2 and v3 descriptions. ## Scenarios Considered - Multi-language support. An Overlay document for each language is used to target a specific OpenAPI description. The Overlay document will likely use a duplicate structure to the original OpenAPI description and replace all `description` properties. - Applying API wide standards. An Overlay document contains update objects that describe standard headers, parameters, responses. These documents would use JMESPath queries to target the appropriate objects in the OpenAPI description. Tooling could be used to target the OpenAPI description rather than using extends. - Add tool specific OpenAPI metadata. Overlay adds additional metadata such as SLA information, client codegen hints or middleware policies. Using Overlays to manage this data separately is valuable when there is a different audience for the data and/or there the information has different sensitivity levels. OpenAPI-Specification-3.1.0/proposals/Alternative Schema/000077500000000000000000000000001401301652500232025ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/proposals/Alternative Schema/CONTRIBUTORS.md000066400000000000000000000001701401301652500254570ustar00rootroot00000000000000* Chuck Heazel [@cmheazel](https://github.com/cmheazel) * Darrel Miller [@darrelmiller](https://github.com/darrelmiller)OpenAPI-Specification-3.1.0/proposals/Alternative Schema/DEVELOPMENT.md000066400000000000000000000005401401301652500253050ustar00rootroot00000000000000## Development Guidelines TBD ## Specification Driving factors TBD ## Specification Change Criteria TBD ## Specification Change Process TBD ## Tracking Process * GitHub is the medium of record for all spec designs, use cases, and so on. ## Release Process TBD ## Draft Features ## Transparency ## Participation ## Community Roles OpenAPI-Specification-3.1.0/proposals/Alternative Schema/alternative_schema_examples.md000066400000000000000000000025531401301652500312650ustar00rootroot00000000000000## Change: Add Alternative Schema Examples The following text is to be inserted after the Alternative Schema Object section. ### Alternative Schema Examples Minimalist usage of alternative schema: schema: x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json Combination of OAS schema and alternative: schema: type: object nullable: true x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json Multiple different versions of alternative schema: schema: anyOf: - x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema-08.json - x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema-07.json Combined alternative schemas: schema: allOf: - x-oas-draft-alternativeSchema: type: xmlSchema location: ./xmlSchema.xsd - x-oas-draft-alternativeSchema: type: schematron location: ./schema.sch Mixed OAS schema and alternative schema: schema: type: array items: x-oas-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json OpenAPI-Specification-3.1.0/proposals/Alternative Schema/alternative_schema_object.adoc000066400000000000000000000016241401301652500312210ustar00rootroot00000000000000## Change: Add the Alternative Schema Object The following text is to be inserted after the XML Object section ### Alternative Schema Object This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed. ==== Fixed Fields |Field Name | Type | Description | |---|:---:|---| |type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. | |location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. | This object MAY be extended with Specification Extensions. OpenAPI-Specification-3.1.0/proposals/Alternative Schema/implementations.md000066400000000000000000000030241401301652500267330ustar00rootroot00000000000000# Implementations ## Overview Below is a list of tooling that claims to implement the Alternative Schema proposal. While support for this feature matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the OpenAPI specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts. These tools are not endorsed by the OAI ## Implementations: #### Low-Level tooling | Title | Project Link | Language | Description | ----------- | ----------- | ----------- | ----------- |TBD |TBD |TBD |TBD | #### Editors | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| |TBD |TBD |TBD |TBD | #### User Interfaces | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| |TBD |TBD |TBD |TBD | #### Mock Servers | Title | Project Link | Language | Description | | -------------- | ------------ | -------- | ----------- | |TBD |TBD |TBD |TBD | #### Server Implementations | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| |TBD |TBD |TBD |TBD | #### Code Generators | Title | Project Link | Language |Description | |----------------|--------------|----------|---------------------| |TBD |TBD |TBD |TBD | OpenAPI-Specification-3.1.0/proposals/Alternative Schema/schema_object.md000066400000000000000000000052571401301652500263230ustar00rootroot00000000000000## Change: Extend the Schema Object to support Alternative Schemas The following content shall be used to replace the Fixed Fields table in the Schema Object section #### Fixed Fields |Field Name | Type | Description | |---|:---:|---| | nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.| | discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. | | readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | | writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. | | xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | | externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema. | example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.| | deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.| |x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | OpenAPI-Specification-3.1.0/schemas/000077500000000000000000000000001401301652500171445ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/schemas/v1.2/000077500000000000000000000000001401301652500176325ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/schemas/v1.2/README.md000066400000000000000000000005051401301652500211110ustar00rootroot00000000000000# Swagger Specification JSON Schemas The work on the JSON Schema for the Swagger Specification was donated to the community by [Francis Galiegue](https://github.com/fge)! Keep in mind that due to some JSON Schema limitations, not all constraints can be described. The missing constraints will be listed here in the future. OpenAPI-Specification-3.1.0/schemas/v1.2/apiDeclaration.json000066400000000000000000000036161401301652500234520ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/apiDeclaration.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "swaggerVersion", "basePath", "apis" ], "properties": { "swaggerVersion": { "enum": [ "1.2" ] }, "apiVersion": { "type": "string" }, "basePath": { "type": "string", "format": "uri", "pattern": "^https?://" }, "resourcePath": { "type": "string", "format": "uri", "pattern": "^/" }, "apis": { "type": "array", "items": { "$ref": "#/definitions/apiObject" } }, "models": { "type": "object", "additionalProperties": { "$ref": "modelsObject.json#" } }, "produces": { "$ref": "#/definitions/mimeTypeArray" }, "consumes": { "$ref": "#/definitions/mimeTypeArray" }, "authorizations": { "$ref": "authorizationObject.json#" } }, "additionalProperties": false, "definitions": { "apiObject": { "type": "object", "required": [ "path", "operations" ], "properties": { "path": { "type": "string", "format": "uri-template", "pattern": "^/" }, "description": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "operationObject.json#" } } }, "additionalProperties": false }, "mimeTypeArray": { "type": "array", "items": { "type": "string", "format": "mime-type" }, "uniqueItems": true } } } OpenAPI-Specification-3.1.0/schemas/v1.2/authorizationObject.json000066400000000000000000000034311401301652500245550ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/authorizationObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/basicAuth" }, { "$ref": "#/definitions/apiKey" }, { "$ref": "#/definitions/oauth2" } ] }, "definitions": { "basicAuth": { "required": [ "type" ], "properties": { "type": { "enum": [ "basicAuth" ] } }, "additionalProperties": false }, "apiKey": { "required": [ "type", "passAs", "keyname" ], "properties": { "type": { "enum": [ "apiKey" ] }, "passAs": { "enum": [ "header", "query" ] }, "keyname": { "type": "string" } }, "additionalProperties": false }, "oauth2": { "type": "object", "required": [ "type", "grantTypes" ], "properties": { "type": { "enum": [ "oauth2" ] }, "scopes": { "type": "array", "items": { "$ref": "#/definitions/oauth2Scope" } }, "grantTypes": { "$ref": "oauth2GrantType.json#" } }, "additionalProperties": false }, "oauth2Scope": { "type": "object", "required": [ "scope" ], "properties": { "scope": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": false } } } OpenAPI-Specification-3.1.0/schemas/v1.2/dataType.json000066400000000000000000000107101401301652500222770ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataType.json#", "$schema": "http://json-schema.org/draft-04/schema#", "description": "Data type as described by the specification (version 1.2)", "type": "object", "oneOf": [ { "$ref": "#/definitions/refType" }, { "$ref": "#/definitions/voidType" }, { "$ref": "#/definitions/primitiveType" }, { "$ref": "#/definitions/modelType" }, { "$ref": "#/definitions/arrayType" } ], "definitions": { "refType": { "required": [ "$ref" ], "properties": { "$ref": { "type": "string" } }, "additionalProperties": false }, "voidType": { "enum": [ { "type": "void" } ] }, "modelType": { "required": [ "type" ], "properties": { "type": { "type": "string", "not": { "enum": [ "boolean", "integer", "number", "string", "array" ] } } }, "additionalProperties": false }, "primitiveType": { "required": [ "type" ], "properties": { "type": { "enum": [ "boolean", "integer", "number", "string" ] }, "format": { "type": "string" }, "defaultValue": { "not": { "type": [ "array", "object", "null" ] } }, "enum": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "minimum": { "type": "string" }, "maximum": { "type": "string" } }, "additionalProperties": false, "dependencies": { "format": { "oneOf": [ { "properties": { "type": { "enum": [ "integer" ] }, "format": { "enum": [ "int32", "int64" ] } } }, { "properties": { "type": { "enum": [ "number" ] }, "format": { "enum": [ "float", "double" ] } } }, { "properties": { "type": { "enum": [ "string" ] }, "format": { "enum": [ "byte", "date", "date-time" ] } } } ] }, "enum": { "properties": { "type": { "enum": [ "string" ] } } }, "minimum": { "properties": { "type": { "enum": [ "integer", "number" ] } } }, "maximum": { "properties": { "type": { "enum": [ "integer", "number" ] } } } } }, "arrayType": { "required": [ "type", "items" ], "properties": { "type": { "enum": [ "array" ] }, "items": { "type": "array", "items": { "$ref": "#/definitions/itemsObject" } }, "uniqueItems": { "type": "boolean" } }, "additionalProperties": false }, "itemsObject": { "oneOf": [ { "$ref": "#/definitions/refType" }, { "allOf": [ { "$ref": "#/definitions/primitiveType" }, { "properties": { "type": {}, "format": {} }, "additionalProperties": false } ] } ] } } }OpenAPI-Specification-3.1.0/schemas/v1.2/dataTypeBase.json000066400000000000000000000050321401301652500230730ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/dataTypeBase.json#", "$schema": "http://json-schema.org/draft-04/schema#", "description": "Data type fields (section 4.3.3)", "type": "object", "oneOf": [ { "required": [ "type" ] }, { "required": [ "$ref" ] } ], "properties": { "type": { "type": "string" }, "$ref": { "type": "string" }, "format": { "type": "string" }, "defaultValue": { "not": { "type": [ "array", "object", "null" ] } }, "enum": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "minItems": 1 }, "minimum": { "type": "string" }, "maximum": { "type": "string" }, "items": { "$ref": "#/definitions/itemsObject" }, "uniqueItems": { "type": "boolean" } }, "dependencies": { "format": { "oneOf": [ { "properties": { "type": { "enum": [ "integer" ] }, "format": { "enum": [ "int32", "int64" ] } } }, { "properties": { "type": { "enum": [ "number" ] }, "format": { "enum": [ "float", "double" ] } } }, { "properties": { "type": { "enum": [ "string" ] }, "format": { "enum": [ "byte", "date", "date-time" ] } } } ] } }, "definitions": { "itemsObject": { "oneOf": [ { "type": "object", "required": [ "$ref" ], "properties": { "$ref": { "type": "string" } }, "additionalProperties": false }, { "allOf": [ { "$ref": "#" }, { "required": [ "type" ], "properties": { "type": {}, "format": {} }, "additionalProperties": false } ] } ] } } } OpenAPI-Specification-3.1.0/schemas/v1.2/infoObject.json000066400000000000000000000012251401301652500226070ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/infoObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "description": "info object (section 5.1.3)", "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "termsOfServiceUrl": { "type": "string", "format": "uri" }, "contact": { "type": "string", "format": "email" }, "license": { "type": "string" }, "licenseUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }OpenAPI-Specification-3.1.0/schemas/v1.2/modelsObject.json000066400000000000000000000017601401301652500231430ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/modelsObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "id", "properties" ], "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/propertyObject" } }, "subTypes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "discriminator": { "type": "string" } }, "dependencies": { "subTypes": [ "discriminator" ] }, "definitions": { "propertyObject": { "allOf": [ { "not": { "$ref": "#" } }, { "$ref": "dataTypeBase.json#" } ] } } } OpenAPI-Specification-3.1.0/schemas/v1.2/oauth2GrantType.json000066400000000000000000000037641401301652500235770ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/oauth2GrantType.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "minProperties": 1, "properties": { "implicit": { "$ref": "#/definitions/implicit" }, "authorization_code": { "$ref": "#/definitions/authorizationCode" } }, "definitions": { "implicit": { "type": "object", "required": [ "loginEndpoint" ], "properties": { "loginEndpoint": { "$ref": "#/definitions/loginEndpoint" }, "tokenName": { "type": "string" } }, "additionalProperties": false }, "authorizationCode": { "type": "object", "required": [ "tokenEndpoint", "tokenRequestEndpoint" ], "properties": { "tokenEndpoint": { "$ref": "#/definitions/tokenEndpoint" }, "tokenRequestEndpoint": { "$ref": "#/definitions/tokenRequestEndpoint" } }, "additionalProperties": false }, "loginEndpoint": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "tokenEndpoint": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "tokenName": { "type": "string" } }, "additionalProperties": false }, "tokenRequestEndpoint": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "clientIdName": { "type": "string" }, "clientSecretName": { "type": "string" } }, "additionalProperties": false } } }OpenAPI-Specification-3.1.0/schemas/v1.2/operationObject.json000066400000000000000000000044671401301652500236670ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/operationObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "allOf": [ { "$ref": "dataTypeBase.json#" }, { "required": [ "method", "nickname", "parameters" ], "properties": { "method": { "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS" ] }, "summary": { "type": "string", "maxLength": 120 }, "notes": { "type": "string" }, "nickname": { "type": "string", "pattern": "^[a-zA-Z0-9_]+$" }, "authorizations": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "authorizationObject.json#/definitions/oauth2Scope" } } }, "parameters": { "type": "array", "items": { "$ref": "parameterObject.json#" } }, "responseMessages": { "type": "array", "items": { "$ref": "#/definitions/responseMessageObject"} }, "produces": { "$ref": "#/definitions/mimeTypeArray" }, "consumes": { "$ref": "#/definitions/mimeTypeArray" }, "deprecated": { "enum": [ "true", "false" ] } } } ], "definitions": { "responseMessageObject": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/definitions/rfc2616section10" }, "message": { "type": "string" }, "responseModel": { "type": "string" } } }, "rfc2616section10": { "type": "integer", "minimum": 100, "maximum": 600, "exclusiveMaximum": true }, "mimeTypeArray": { "type": "array", "items": { "type": "string", "format": "mime-type" }, "uniqueItems": true } } } OpenAPI-Specification-3.1.0/schemas/v1.2/parameterObject.json000066400000000000000000000024061401301652500236360ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/parameterObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "allOf": [ { "$ref": "dataTypeBase.json#" }, { "required": [ "paramType", "name" ], "properties": { "paramType": { "enum": [ "path", "query", "body", "header", "form" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "allowMultiple": { "type": "boolean" } } }, { "description": "type File requires special paramType and consumes", "oneOf": [ { "properties": { "type": { "not": { "enum": [ "File" ] } } } }, { "properties": { "type": { "enum": [ "File" ] }, "paramType": { "enum": [ "form" ] }, "consumes": { "enum": [ "multipart/form-data" ] } } } ] } ] } OpenAPI-Specification-3.1.0/schemas/v1.2/resourceListing.json000066400000000000000000000011201401301652500237000ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceListing.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "swaggerVersion", "apis" ], "properties": { "swaggerVersion": { "enum": [ "1.2" ] }, "apis": { "type": "array", "items": { "$ref": "resourceObject.json#" } }, "apiVersion": { "type": "string" }, "info": { "$ref": "infoObject.json#" }, "authorizations": { "$ref": "authorizationObject.json#" } } } OpenAPI-Specification-3.1.0/schemas/v1.2/resourceObject.json000066400000000000000000000006011401301652500235000ustar00rootroot00000000000000{ "id": "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v1.2/resourceObject.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "additionalProperties": false }OpenAPI-Specification-3.1.0/schemas/v2.0/000077500000000000000000000000001401301652500176315ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/schemas/v2.0/README.md000066400000000000000000000003701401301652500211100ustar00rootroot00000000000000# OpenAPI Specification v2.0 JSON Schema This is the JSON Schema file for the OpenAPI Specification version 2.0. Download and install it via NPM. ## Install via NPM ```shell npm install --save swagger-schema-official ``` ## License Apache-2.0 OpenAPI-Specification-3.1.0/schemas/v2.0/schema.json000066400000000000000000001164671401301652500220030ustar00rootroot00000000000000{ "title": "A JSON Schema for Swagger 2.0 API.", "id": "http://swagger.io/v2/schema.json#", "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "required": [ "swagger", "info", "paths" ], "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "swagger": { "type": "string", "enum": [ "2.0" ], "description": "The Swagger version of this document." }, "info": { "$ref": "#/definitions/info" }, "host": { "type": "string", "pattern": "^[^{}/ :\\\\]+(?::\\d+)?$", "description": "The host (name or ip) of the API. Example: 'swagger.io'" }, "basePath": { "type": "string", "pattern": "^/", "description": "The base path to the API. Example: '/api'." }, "schemes": { "$ref": "#/definitions/schemesList" }, "consumes": { "description": "A list of MIME types accepted by the API.", "allOf": [ { "$ref": "#/definitions/mediaTypeList" } ] }, "produces": { "description": "A list of MIME types the API can produce.", "allOf": [ { "$ref": "#/definitions/mediaTypeList" } ] }, "paths": { "$ref": "#/definitions/paths" }, "definitions": { "$ref": "#/definitions/definitions" }, "parameters": { "$ref": "#/definitions/parameterDefinitions" }, "responses": { "$ref": "#/definitions/responseDefinitions" }, "security": { "$ref": "#/definitions/security" }, "securityDefinitions": { "$ref": "#/definitions/securityDefinitions" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/tag" }, "uniqueItems": true }, "externalDocs": { "$ref": "#/definitions/externalDocs" } }, "definitions": { "info": { "type": "object", "description": "General information about the API.", "required": [ "version", "title" ], "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "title": { "type": "string", "description": "A unique and precise title of the API." }, "version": { "type": "string", "description": "A semantic version number of the API." }, "description": { "type": "string", "description": "A longer description of the API. Should be different from the title. GitHub Flavored Markdown is allowed." }, "termsOfService": { "type": "string", "description": "The terms of service for the API." }, "contact": { "$ref": "#/definitions/contact" }, "license": { "$ref": "#/definitions/license" } } }, "contact": { "type": "object", "description": "Contact information for the owners of the API.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The identifying name of the contact person/organization." }, "url": { "type": "string", "description": "The URL pointing to the contact information.", "format": "uri" }, "email": { "type": "string", "description": "The email address of the contact person/organization.", "format": "email" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "license": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The name of the license type. It's encouraged to use an OSI compatible license." }, "url": { "type": "string", "description": "The URL pointing to the license.", "format": "uri" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "paths": { "type": "object", "description": "Relative paths to the individual endpoints. They must be relative to the 'basePath'.", "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" }, "^/": { "$ref": "#/definitions/pathItem" } }, "additionalProperties": false }, "definitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/schema" }, "description": "One or more JSON objects describing the schemas being consumed and produced by the API." }, "parameterDefinitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/parameter" }, "description": "One or more JSON representations for parameters" }, "responseDefinitions": { "type": "object", "additionalProperties": { "$ref": "#/definitions/response" }, "description": "One or more JSON representations for responses" }, "externalDocs": { "type": "object", "additionalProperties": false, "description": "information about external documentation", "required": [ "url" ], "properties": { "description": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "examples": { "type": "object", "additionalProperties": true }, "mimeType": { "type": "string", "description": "The MIME type of the HTTP message." }, "operation": { "type": "object", "required": [ "responses" ], "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "tags": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "summary": { "type": "string", "description": "A brief summary of the operation." }, "description": { "type": "string", "description": "A longer description of the operation, GitHub Flavored Markdown is allowed." }, "externalDocs": { "$ref": "#/definitions/externalDocs" }, "operationId": { "type": "string", "description": "A unique identifier of the operation." }, "produces": { "description": "A list of MIME types the API can produce.", "allOf": [ { "$ref": "#/definitions/mediaTypeList" } ] }, "consumes": { "description": "A list of MIME types the API can consume.", "allOf": [ { "$ref": "#/definitions/mediaTypeList" } ] }, "parameters": { "$ref": "#/definitions/parametersList" }, "responses": { "$ref": "#/definitions/responses" }, "schemes": { "$ref": "#/definitions/schemesList" }, "deprecated": { "type": "boolean", "default": false }, "security": { "$ref": "#/definitions/security" } } }, "pathItem": { "type": "object", "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "$ref": { "type": "string" }, "get": { "$ref": "#/definitions/operation" }, "put": { "$ref": "#/definitions/operation" }, "post": { "$ref": "#/definitions/operation" }, "delete": { "$ref": "#/definitions/operation" }, "options": { "$ref": "#/definitions/operation" }, "head": { "$ref": "#/definitions/operation" }, "patch": { "$ref": "#/definitions/operation" }, "parameters": { "$ref": "#/definitions/parametersList" } } }, "responses": { "type": "object", "description": "Response objects names can either be any valid HTTP status code or 'default'.", "minProperties": 1, "additionalProperties": false, "patternProperties": { "^([0-9]{3})$|^(default)$": { "$ref": "#/definitions/responseValue" }, "^x-": { "$ref": "#/definitions/vendorExtension" } }, "not": { "type": "object", "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } } }, "responseValue": { "oneOf": [ { "$ref": "#/definitions/response" }, { "$ref": "#/definitions/jsonReference" } ] }, "response": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string" }, "schema": { "oneOf": [ { "$ref": "#/definitions/schema" }, { "$ref": "#/definitions/fileSchema" } ] }, "headers": { "$ref": "#/definitions/headers" }, "examples": { "$ref": "#/definitions/examples" } }, "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "headers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/header" } }, "header": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormat" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "vendorExtension": { "description": "Any property starting with x- is valid.", "additionalProperties": true, "additionalItems": true }, "bodyParameter": { "type": "object", "required": [ "name", "in", "schema" ], "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "description": { "type": "string", "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "name": { "type": "string", "description": "The name of the parameter." }, "in": { "type": "string", "description": "Determines the location of the parameter.", "enum": [ "body" ] }, "required": { "type": "boolean", "description": "Determines whether or not this parameter is required or optional.", "default": false }, "schema": { "$ref": "#/definitions/schema" } }, "additionalProperties": false }, "headerParameterSubSchema": { "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "required": { "type": "boolean", "description": "Determines whether or not this parameter is required or optional.", "default": false }, "in": { "type": "string", "description": "Determines the location of the parameter.", "enum": [ "header" ] }, "description": { "type": "string", "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "name": { "type": "string", "description": "The name of the parameter." }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "integer", "array" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormat" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" } } }, "queryParameterSubSchema": { "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "required": { "type": "boolean", "description": "Determines whether or not this parameter is required or optional.", "default": false }, "in": { "type": "string", "description": "Determines the location of the parameter.", "enum": [ "query" ] }, "description": { "type": "string", "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "name": { "type": "string", "description": "The name of the parameter." }, "allowEmptyValue": { "type": "boolean", "default": false, "description": "allows sending a parameter by name only or with an empty value." }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "integer", "array" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormatWithMulti" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" } } }, "formDataParameterSubSchema": { "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "required": { "type": "boolean", "description": "Determines whether or not this parameter is required or optional.", "default": false }, "in": { "type": "string", "description": "Determines the location of the parameter.", "enum": [ "formData" ] }, "description": { "type": "string", "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "name": { "type": "string", "description": "The name of the parameter." }, "allowEmptyValue": { "type": "boolean", "default": false, "description": "allows sending a parameter by name only or with an empty value." }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "integer", "array", "file" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormatWithMulti" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" } } }, "pathParameterSubSchema": { "additionalProperties": false, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "required": [ "required" ], "properties": { "required": { "type": "boolean", "enum": [ true ], "description": "Determines whether or not this parameter is required or optional." }, "in": { "type": "string", "description": "Determines the location of the parameter.", "enum": [ "path" ] }, "description": { "type": "string", "description": "A brief description of the parameter. This could contain examples of use. GitHub Flavored Markdown is allowed." }, "name": { "type": "string", "description": "The name of the parameter." }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "integer", "array" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormat" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" } } }, "nonBodyParameter": { "type": "object", "required": [ "name", "in", "type" ], "oneOf": [ { "$ref": "#/definitions/headerParameterSubSchema" }, { "$ref": "#/definitions/formDataParameterSubSchema" }, { "$ref": "#/definitions/queryParameterSubSchema" }, { "$ref": "#/definitions/pathParameterSubSchema" } ] }, "parameter": { "oneOf": [ { "$ref": "#/definitions/bodyParameter" }, { "$ref": "#/definitions/nonBodyParameter" } ] }, "schema": { "type": "object", "description": "A deterministic version of a JSON Schema object.", "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "properties": { "$ref": { "type": "string" }, "format": { "type": "string" }, "title": { "$ref": "http://json-schema.org/draft-04/schema#/properties/title" }, "description": { "$ref": "http://json-schema.org/draft-04/schema#/properties/description" }, "default": { "$ref": "http://json-schema.org/draft-04/schema#/properties/default" }, "multipleOf": { "$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf" }, "maximum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/maximum" }, "exclusiveMaximum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum" }, "minimum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/minimum" }, "exclusiveMinimum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum" }, "maxLength": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger" }, "minLength": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0" }, "pattern": { "$ref": "http://json-schema.org/draft-04/schema#/properties/pattern" }, "maxItems": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger" }, "minItems": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0" }, "uniqueItems": { "$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems" }, "maxProperties": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger" }, "minProperties": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0" }, "required": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/stringArray" }, "enum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/enum" }, "additionalProperties": { "anyOf": [ { "$ref": "#/definitions/schema" }, { "type": "boolean" } ], "default": {} }, "type": { "$ref": "http://json-schema.org/draft-04/schema#/properties/type" }, "items": { "anyOf": [ { "$ref": "#/definitions/schema" }, { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/schema" } } ], "default": {} }, "allOf": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/schema" } }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/definitions/schema" }, "default": {} }, "discriminator": { "type": "string" }, "readOnly": { "type": "boolean", "default": false }, "xml": { "$ref": "#/definitions/xml" }, "externalDocs": { "$ref": "#/definitions/externalDocs" }, "example": {} }, "additionalProperties": false }, "fileSchema": { "type": "object", "description": "A deterministic version of a JSON Schema object.", "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } }, "required": [ "type" ], "properties": { "format": { "type": "string" }, "title": { "$ref": "http://json-schema.org/draft-04/schema#/properties/title" }, "description": { "$ref": "http://json-schema.org/draft-04/schema#/properties/description" }, "default": { "$ref": "http://json-schema.org/draft-04/schema#/properties/default" }, "required": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/stringArray" }, "type": { "type": "string", "enum": [ "file" ] }, "readOnly": { "type": "boolean", "default": false }, "externalDocs": { "$ref": "#/definitions/externalDocs" }, "example": {} }, "additionalProperties": false }, "primitivesItems": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "string", "number", "integer", "boolean", "array" ] }, "format": { "type": "string" }, "items": { "$ref": "#/definitions/primitivesItems" }, "collectionFormat": { "$ref": "#/definitions/collectionFormat" }, "default": { "$ref": "#/definitions/default" }, "maximum": { "$ref": "#/definitions/maximum" }, "exclusiveMaximum": { "$ref": "#/definitions/exclusiveMaximum" }, "minimum": { "$ref": "#/definitions/minimum" }, "exclusiveMinimum": { "$ref": "#/definitions/exclusiveMinimum" }, "maxLength": { "$ref": "#/definitions/maxLength" }, "minLength": { "$ref": "#/definitions/minLength" }, "pattern": { "$ref": "#/definitions/pattern" }, "maxItems": { "$ref": "#/definitions/maxItems" }, "minItems": { "$ref": "#/definitions/minItems" }, "uniqueItems": { "$ref": "#/definitions/uniqueItems" }, "enum": { "$ref": "#/definitions/enum" }, "multipleOf": { "$ref": "#/definitions/multipleOf" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "security": { "type": "array", "items": { "$ref": "#/definitions/securityRequirement" }, "uniqueItems": true }, "securityRequirement": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "xml": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "namespace": { "type": "string" }, "prefix": { "type": "string" }, "attribute": { "type": "boolean", "default": false }, "wrapped": { "type": "boolean", "default": false } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "tag": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "externalDocs": { "$ref": "#/definitions/externalDocs" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "securityDefinitions": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/basicAuthenticationSecurity" }, { "$ref": "#/definitions/apiKeySecurity" }, { "$ref": "#/definitions/oauth2ImplicitSecurity" }, { "$ref": "#/definitions/oauth2PasswordSecurity" }, { "$ref": "#/definitions/oauth2ApplicationSecurity" }, { "$ref": "#/definitions/oauth2AccessCodeSecurity" } ] } }, "basicAuthenticationSecurity": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "basic" ] }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "apiKeySecurity": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "in" ], "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "name": { "type": "string" }, "in": { "type": "string", "enum": [ "header", "query" ] }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "oauth2ImplicitSecurity": { "type": "object", "additionalProperties": false, "required": [ "type", "flow", "authorizationUrl" ], "properties": { "type": { "type": "string", "enum": [ "oauth2" ] }, "flow": { "type": "string", "enum": [ "implicit" ] }, "scopes": { "$ref": "#/definitions/oauth2Scopes" }, "authorizationUrl": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "oauth2PasswordSecurity": { "type": "object", "additionalProperties": false, "required": [ "type", "flow", "tokenUrl" ], "properties": { "type": { "type": "string", "enum": [ "oauth2" ] }, "flow": { "type": "string", "enum": [ "password" ] }, "scopes": { "$ref": "#/definitions/oauth2Scopes" }, "tokenUrl": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "oauth2ApplicationSecurity": { "type": "object", "additionalProperties": false, "required": [ "type", "flow", "tokenUrl" ], "properties": { "type": { "type": "string", "enum": [ "oauth2" ] }, "flow": { "type": "string", "enum": [ "application" ] }, "scopes": { "$ref": "#/definitions/oauth2Scopes" }, "tokenUrl": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "oauth2AccessCodeSecurity": { "type": "object", "additionalProperties": false, "required": [ "type", "flow", "authorizationUrl", "tokenUrl" ], "properties": { "type": { "type": "string", "enum": [ "oauth2" ] }, "flow": { "type": "string", "enum": [ "accessCode" ] }, "scopes": { "$ref": "#/definitions/oauth2Scopes" }, "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { "$ref": "#/definitions/vendorExtension" } } }, "oauth2Scopes": { "type": "object", "additionalProperties": { "type": "string" } }, "mediaTypeList": { "type": "array", "items": { "$ref": "#/definitions/mimeType" }, "uniqueItems": true }, "parametersList": { "type": "array", "description": "The parameters needed to send a valid API call.", "additionalItems": false, "items": { "oneOf": [ { "$ref": "#/definitions/parameter" }, { "$ref": "#/definitions/jsonReference" } ] }, "uniqueItems": true }, "schemesList": { "type": "array", "description": "The transfer protocol of the API.", "items": { "type": "string", "enum": [ "http", "https", "ws", "wss" ] }, "uniqueItems": true }, "collectionFormat": { "type": "string", "enum": [ "csv", "ssv", "tsv", "pipes" ], "default": "csv" }, "collectionFormatWithMulti": { "type": "string", "enum": [ "csv", "ssv", "tsv", "pipes", "multi" ], "default": "csv" }, "title": { "$ref": "http://json-schema.org/draft-04/schema#/properties/title" }, "description": { "$ref": "http://json-schema.org/draft-04/schema#/properties/description" }, "default": { "$ref": "http://json-schema.org/draft-04/schema#/properties/default" }, "multipleOf": { "$ref": "http://json-schema.org/draft-04/schema#/properties/multipleOf" }, "maximum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/maximum" }, "exclusiveMaximum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMaximum" }, "minimum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/minimum" }, "exclusiveMinimum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/exclusiveMinimum" }, "maxLength": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger" }, "minLength": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0" }, "pattern": { "$ref": "http://json-schema.org/draft-04/schema#/properties/pattern" }, "maxItems": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveInteger" }, "minItems": { "$ref": "http://json-schema.org/draft-04/schema#/definitions/positiveIntegerDefault0" }, "uniqueItems": { "$ref": "http://json-schema.org/draft-04/schema#/properties/uniqueItems" }, "enum": { "$ref": "http://json-schema.org/draft-04/schema#/properties/enum" }, "jsonReference": { "type": "object", "required": [ "$ref" ], "additionalProperties": false, "properties": { "$ref": { "type": "string" } } } } }OpenAPI-Specification-3.1.0/schemas/v3.0/000077500000000000000000000000001401301652500176325ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/schemas/v3.0/README.md000066400000000000000000000015721401301652500211160ustar00rootroot00000000000000OpenAPI 3.0.X JSON Schema --- Here you can find the JSON Schema for validating OpenAPI definitions of versions 3.0.X. As a reminder, the JSON Schema is not the source of truth for the Specification. In cases of conflicts between the Specification itself and the JSON Schema, the Specification wins. Also, some Specification constraints cannot be represented with the JSON Schema so it's highly recommended to employ other methods to ensure compliance. The iteration version of the JSON Schema can be found in the `id` field. For example, the value of `id: https://spec.openapis.org/oas/3.0/schema/2019-04-02` means this iteration was created on April 2nd, 2019. To submit improvements to the schema, modify the schema.yaml file only. The TSC will then: - Run tests on the updated schema - Update the iteration version - Convert the schema.yaml to schema.json - Publish the new version OpenAPI-Specification-3.1.0/schemas/v3.0/schema.json000066400000000000000000001052001401301652500217630ustar00rootroot00000000000000{ "id": "https://spec.openapis.org/oas/3.0/schema/2019-04-02", "$schema": "http://json-schema.org/draft-04/schema#", "description": "Validation schema for OpenAPI Specification 3.0.X.", "type": "object", "required": [ "openapi", "info", "paths" ], "properties": { "openapi": { "type": "string", "pattern": "^3\\.0\\.\\d(-.+)?$" }, "info": { "$ref": "#/definitions/Info" }, "externalDocs": { "$ref": "#/definitions/ExternalDocumentation" }, "servers": { "type": "array", "items": { "$ref": "#/definitions/Server" } }, "security": { "type": "array", "items": { "$ref": "#/definitions/SecurityRequirement" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/Tag" }, "uniqueItems": true }, "paths": { "$ref": "#/definitions/Paths" }, "components": { "$ref": "#/definitions/Components" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "definitions": { "Reference": { "type": "object", "required": [ "$ref" ], "patternProperties": { "^\\$ref$": { "type": "string", "format": "uri-reference" } } }, "Info": { "type": "object", "required": [ "title", "version" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "termsOfService": { "type": "string", "format": "uri-reference" }, "contact": { "$ref": "#/definitions/Contact" }, "license": { "$ref": "#/definitions/License" }, "version": { "type": "string" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Contact": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" }, "email": { "type": "string", "format": "email" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "License": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Server": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "$ref": "#/definitions/ServerVariable" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "ServerVariable": { "type": "object", "required": [ "default" ], "properties": { "enum": { "type": "array", "items": { "type": "string" } }, "default": { "type": "string" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Components": { "type": "object", "properties": { "schemas": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] } } }, "responses": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Response" } ] } } }, "parameters": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Parameter" } ] } } }, "examples": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Example" } ] } } }, "requestBodies": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/RequestBody" } ] } } }, "headers": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Header" } ] } } }, "securitySchemes": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/SecurityScheme" } ] } } }, "links": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Link" } ] } } }, "callbacks": { "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "oneOf": [ { "$ref": "#/definitions/Reference" }, { "$ref": "#/definitions/Callback" } ] } } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Schema": { "type": "object", "properties": { "title": { "type": "string" }, "multipleOf": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "maximum": { "type": "number" }, "exclusiveMaximum": { "type": "boolean", "default": false }, "minimum": { "type": "number" }, "exclusiveMinimum": { "type": "boolean", "default": false }, "maxLength": { "type": "integer", "minimum": 0 }, "minLength": { "type": "integer", "minimum": 0, "default": 0 }, "pattern": { "type": "string", "format": "regex" }, "maxItems": { "type": "integer", "minimum": 0 }, "minItems": { "type": "integer", "minimum": 0, "default": 0 }, "uniqueItems": { "type": "boolean", "default": false }, "maxProperties": { "type": "integer", "minimum": 0 }, "minProperties": { "type": "integer", "minimum": 0, "default": 0 }, "required": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "enum": { "type": "array", "items": { }, "minItems": 1, "uniqueItems": false }, "type": { "type": "string", "enum": [ "array", "boolean", "integer", "number", "object", "string" ] }, "not": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] }, "allOf": { "type": "array", "items": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] } }, "oneOf": { "type": "array", "items": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] } }, "anyOf": { "type": "array", "items": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] } }, "items": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] }, "properties": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] } }, "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" }, { "type": "boolean" } ], "default": true }, "description": { "type": "string" }, "format": { "type": "string" }, "default": { }, "nullable": { "type": "boolean", "default": false }, "discriminator": { "$ref": "#/definitions/Discriminator" }, "readOnly": { "type": "boolean", "default": false }, "writeOnly": { "type": "boolean", "default": false }, "example": { }, "externalDocs": { "$ref": "#/definitions/ExternalDocumentation" }, "deprecated": { "type": "boolean", "default": false }, "xml": { "$ref": "#/definitions/XML" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Discriminator": { "type": "object", "required": [ "propertyName" ], "properties": { "propertyName": { "type": "string" }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } } } }, "XML": { "type": "object", "properties": { "name": { "type": "string" }, "namespace": { "type": "string", "format": "uri" }, "prefix": { "type": "string" }, "attribute": { "type": "boolean", "default": false }, "wrapped": { "type": "boolean", "default": false } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Response": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Header" }, { "$ref": "#/definitions/Reference" } ] } }, "content": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MediaType" } }, "links": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Link" }, { "$ref": "#/definitions/Reference" } ] } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "MediaType": { "type": "object", "properties": { "schema": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] }, "example": { }, "examples": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Example" }, { "$ref": "#/definitions/Reference" } ] } }, "encoding": { "type": "object", "additionalProperties": { "$ref": "#/definitions/Encoding" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "allOf": [ { "$ref": "#/definitions/ExampleXORExamples" } ] }, "Example": { "type": "object", "properties": { "summary": { "type": "string" }, "description": { "type": "string" }, "value": { }, "externalValue": { "type": "string", "format": "uri-reference" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Header": { "type": "object", "properties": { "description": { "type": "string" }, "required": { "type": "boolean", "default": false }, "deprecated": { "type": "boolean", "default": false }, "allowEmptyValue": { "type": "boolean", "default": false }, "style": { "type": "string", "enum": [ "simple" ], "default": "simple" }, "explode": { "type": "boolean" }, "allowReserved": { "type": "boolean", "default": false }, "schema": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] }, "content": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MediaType" }, "minProperties": 1, "maxProperties": 1 }, "example": { }, "examples": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Example" }, { "$ref": "#/definitions/Reference" } ] } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "allOf": [ { "$ref": "#/definitions/ExampleXORExamples" }, { "$ref": "#/definitions/SchemaXORContent" } ] }, "Paths": { "type": "object", "patternProperties": { "^\\/": { "$ref": "#/definitions/PathItem" }, "^x-": { } }, "additionalProperties": false }, "PathItem": { "type": "object", "properties": { "$ref": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" }, "servers": { "type": "array", "items": { "$ref": "#/definitions/Server" } }, "parameters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/definitions/Parameter" }, { "$ref": "#/definitions/Reference" } ] }, "uniqueItems": true } }, "patternProperties": { "^(get|put|post|delete|options|head|patch|trace)$": { "$ref": "#/definitions/Operation" }, "^x-": { } }, "additionalProperties": false }, "Operation": { "type": "object", "required": [ "responses" ], "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" }, "description": { "type": "string" }, "externalDocs": { "$ref": "#/definitions/ExternalDocumentation" }, "operationId": { "type": "string" }, "parameters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/definitions/Parameter" }, { "$ref": "#/definitions/Reference" } ] }, "uniqueItems": true }, "requestBody": { "oneOf": [ { "$ref": "#/definitions/RequestBody" }, { "$ref": "#/definitions/Reference" } ] }, "responses": { "$ref": "#/definitions/Responses" }, "callbacks": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Callback" }, { "$ref": "#/definitions/Reference" } ] } }, "deprecated": { "type": "boolean", "default": false }, "security": { "type": "array", "items": { "$ref": "#/definitions/SecurityRequirement" } }, "servers": { "type": "array", "items": { "$ref": "#/definitions/Server" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Responses": { "type": "object", "properties": { "default": { "oneOf": [ { "$ref": "#/definitions/Response" }, { "$ref": "#/definitions/Reference" } ] } }, "patternProperties": { "^[1-5](?:\\d{2}|XX)$": { "oneOf": [ { "$ref": "#/definitions/Response" }, { "$ref": "#/definitions/Reference" } ] }, "^x-": { } }, "minProperties": 1, "additionalProperties": false }, "SecurityRequirement": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "Tag": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "externalDocs": { "$ref": "#/definitions/ExternalDocumentation" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "ExternalDocumentation": { "type": "object", "required": [ "url" ], "properties": { "description": { "type": "string" }, "url": { "type": "string", "format": "uri-reference" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "ExampleXORExamples": { "description": "Example and examples are mutually exclusive", "not": { "required": [ "example", "examples" ] } }, "SchemaXORContent": { "description": "Schema and content are mutually exclusive, at least one is required", "not": { "required": [ "schema", "content" ] }, "oneOf": [ { "required": [ "schema" ] }, { "required": [ "content" ], "description": "Some properties are not allowed if content is present", "allOf": [ { "not": { "required": [ "style" ] } }, { "not": { "required": [ "explode" ] } }, { "not": { "required": [ "allowReserved" ] } }, { "not": { "required": [ "example" ] } }, { "not": { "required": [ "examples" ] } } ] } ] }, "Parameter": { "type": "object", "properties": { "name": { "type": "string" }, "in": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean", "default": false }, "deprecated": { "type": "boolean", "default": false }, "allowEmptyValue": { "type": "boolean", "default": false }, "style": { "type": "string" }, "explode": { "type": "boolean" }, "allowReserved": { "type": "boolean", "default": false }, "schema": { "oneOf": [ { "$ref": "#/definitions/Schema" }, { "$ref": "#/definitions/Reference" } ] }, "content": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MediaType" }, "minProperties": 1, "maxProperties": 1 }, "example": { }, "examples": { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Example" }, { "$ref": "#/definitions/Reference" } ] } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "required": [ "name", "in" ], "allOf": [ { "$ref": "#/definitions/ExampleXORExamples" }, { "$ref": "#/definitions/SchemaXORContent" }, { "$ref": "#/definitions/ParameterLocation" } ] }, "ParameterLocation": { "description": "Parameter location", "oneOf": [ { "description": "Parameter in path", "required": [ "required" ], "properties": { "in": { "enum": [ "path" ] }, "style": { "enum": [ "matrix", "label", "simple" ], "default": "simple" }, "required": { "enum": [ true ] } } }, { "description": "Parameter in query", "properties": { "in": { "enum": [ "query" ] }, "style": { "enum": [ "form", "spaceDelimited", "pipeDelimited", "deepObject" ], "default": "form" } } }, { "description": "Parameter in header", "properties": { "in": { "enum": [ "header" ] }, "style": { "enum": [ "simple" ], "default": "simple" } } }, { "description": "Parameter in cookie", "properties": { "in": { "enum": [ "cookie" ] }, "style": { "enum": [ "form" ], "default": "form" } } } ] }, "RequestBody": { "type": "object", "required": [ "content" ], "properties": { "description": { "type": "string" }, "content": { "type": "object", "additionalProperties": { "$ref": "#/definitions/MediaType" } }, "required": { "type": "boolean", "default": false } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "SecurityScheme": { "oneOf": [ { "$ref": "#/definitions/APIKeySecurityScheme" }, { "$ref": "#/definitions/HTTPSecurityScheme" }, { "$ref": "#/definitions/OAuth2SecurityScheme" }, { "$ref": "#/definitions/OpenIdConnectSecurityScheme" } ] }, "APIKeySecurityScheme": { "type": "object", "required": [ "type", "name", "in" ], "properties": { "type": { "type": "string", "enum": [ "apiKey" ] }, "name": { "type": "string" }, "in": { "type": "string", "enum": [ "header", "query", "cookie" ] }, "description": { "type": "string" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "HTTPSecurityScheme": { "type": "object", "required": [ "scheme", "type" ], "properties": { "scheme": { "type": "string" }, "bearerFormat": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "http" ] } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "oneOf": [ { "description": "Bearer", "properties": { "scheme": { "enum": [ "bearer" ] } } }, { "description": "Non Bearer", "not": { "required": [ "bearerFormat" ] }, "properties": { "scheme": { "not": { "enum": [ "bearer" ] } } } } ] }, "OAuth2SecurityScheme": { "type": "object", "required": [ "type", "flows" ], "properties": { "type": { "type": "string", "enum": [ "oauth2" ] }, "flows": { "$ref": "#/definitions/OAuthFlows" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "OpenIdConnectSecurityScheme": { "type": "object", "required": [ "type", "openIdConnectUrl" ], "properties": { "type": { "type": "string", "enum": [ "openIdConnect" ] }, "openIdConnectUrl": { "type": "string", "format": "uri-reference" }, "description": { "type": "string" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "OAuthFlows": { "type": "object", "properties": { "implicit": { "$ref": "#/definitions/ImplicitOAuthFlow" }, "password": { "$ref": "#/definitions/PasswordOAuthFlow" }, "clientCredentials": { "$ref": "#/definitions/ClientCredentialsFlow" }, "authorizationCode": { "$ref": "#/definitions/AuthorizationCodeOAuthFlow" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "ImplicitOAuthFlow": { "type": "object", "required": [ "authorizationUrl", "scopes" ], "properties": { "authorizationUrl": { "type": "string", "format": "uri-reference" }, "refreshUrl": { "type": "string", "format": "uri-reference" }, "scopes": { "type": "object", "additionalProperties": { "type": "string" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "PasswordOAuthFlow": { "type": "object", "required": [ "tokenUrl" ], "properties": { "tokenUrl": { "type": "string", "format": "uri-reference" }, "refreshUrl": { "type": "string", "format": "uri-reference" }, "scopes": { "type": "object", "additionalProperties": { "type": "string" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "ClientCredentialsFlow": { "type": "object", "required": [ "tokenUrl" ], "properties": { "tokenUrl": { "type": "string", "format": "uri-reference" }, "refreshUrl": { "type": "string", "format": "uri-reference" }, "scopes": { "type": "object", "additionalProperties": { "type": "string" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "AuthorizationCodeOAuthFlow": { "type": "object", "required": [ "authorizationUrl", "tokenUrl" ], "properties": { "authorizationUrl": { "type": "string", "format": "uri-reference" }, "tokenUrl": { "type": "string", "format": "uri-reference" }, "refreshUrl": { "type": "string", "format": "uri-reference" }, "scopes": { "type": "object", "additionalProperties": { "type": "string" } } }, "patternProperties": { "^x-": { } }, "additionalProperties": false }, "Link": { "type": "object", "properties": { "operationId": { "type": "string" }, "operationRef": { "type": "string", "format": "uri-reference" }, "parameters": { "type": "object", "additionalProperties": { } }, "requestBody": { }, "description": { "type": "string" }, "server": { "$ref": "#/definitions/Server" } }, "patternProperties": { "^x-": { } }, "additionalProperties": false, "not": { "description": "Operation Id and Operation Ref are mutually exclusive", "required": [ "operationId", "operationRef" ] } }, "Callback": { "type": "object", "additionalProperties": { "$ref": "#/definitions/PathItem" }, "patternProperties": { "^x-": { } } }, "Encoding": { "type": "object", "properties": { "contentType": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "$ref": "#/definitions/Header" } }, "style": { "type": "string", "enum": [ "form", "spaceDelimited", "pipeDelimited", "deepObject" ] }, "explode": { "type": "boolean" }, "allowReserved": { "type": "boolean", "default": false } }, "additionalProperties": false } } }OpenAPI-Specification-3.1.0/schemas/v3.0/schema.yaml000066400000000000000000000530511401301652500217620ustar00rootroot00000000000000id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 $schema: http://json-schema.org/draft-04/schema# description: Validation schema for OpenAPI Specification 3.0.X. type: object required: - openapi - info - paths properties: openapi: type: string pattern: ^3\.0\.\d(-.+)?$ info: $ref: '#/definitions/Info' externalDocs: $ref: '#/definitions/ExternalDocumentation' servers: type: array items: $ref: '#/definitions/Server' security: type: array items: $ref: '#/definitions/SecurityRequirement' tags: type: array items: $ref: '#/definitions/Tag' uniqueItems: true paths: $ref: '#/definitions/Paths' components: $ref: '#/definitions/Components' patternProperties: '^x-': {} additionalProperties: false definitions: Reference: type: object required: - $ref patternProperties: '^\$ref$': type: string format: uri-reference Info: type: object required: - title - version properties: title: type: string description: type: string termsOfService: type: string format: uri-reference contact: $ref: '#/definitions/Contact' license: $ref: '#/definitions/License' version: type: string patternProperties: '^x-': {} additionalProperties: false Contact: type: object properties: name: type: string url: type: string format: uri-reference email: type: string format: email patternProperties: '^x-': {} additionalProperties: false License: type: object required: - name properties: name: type: string url: type: string format: uri-reference patternProperties: '^x-': {} additionalProperties: false Server: type: object required: - url properties: url: type: string description: type: string variables: type: object additionalProperties: $ref: '#/definitions/ServerVariable' patternProperties: '^x-': {} additionalProperties: false ServerVariable: type: object required: - default properties: enum: type: array items: type: string default: type: string description: type: string patternProperties: '^x-': {} additionalProperties: false Components: type: object properties: schemas: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' responses: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Response' parameters: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Parameter' examples: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Example' requestBodies: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/RequestBody' headers: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Header' securitySchemes: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/SecurityScheme' links: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Link' callbacks: type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': oneOf: - $ref: '#/definitions/Reference' - $ref: '#/definitions/Callback' patternProperties: '^x-': {} additionalProperties: false Schema: type: object properties: title: type: string multipleOf: type: number minimum: 0 exclusiveMinimum: true maximum: type: number exclusiveMaximum: type: boolean default: false minimum: type: number exclusiveMinimum: type: boolean default: false maxLength: type: integer minimum: 0 minLength: type: integer minimum: 0 default: 0 pattern: type: string format: regex maxItems: type: integer minimum: 0 minItems: type: integer minimum: 0 default: 0 uniqueItems: type: boolean default: false maxProperties: type: integer minimum: 0 minProperties: type: integer minimum: 0 default: 0 required: type: array items: type: string minItems: 1 uniqueItems: true enum: type: array items: {} minItems: 1 uniqueItems: false type: type: string enum: - array - boolean - integer - number - object - string not: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' allOf: type: array items: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' oneOf: type: array items: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' anyOf: type: array items: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' items: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' properties: type: object additionalProperties: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' additionalProperties: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' - type: boolean default: true description: type: string format: type: string default: {} nullable: type: boolean default: false discriminator: $ref: '#/definitions/Discriminator' readOnly: type: boolean default: false writeOnly: type: boolean default: false example: {} externalDocs: $ref: '#/definitions/ExternalDocumentation' deprecated: type: boolean default: false xml: $ref: '#/definitions/XML' patternProperties: '^x-': {} additionalProperties: false Discriminator: type: object required: - propertyName properties: propertyName: type: string mapping: type: object additionalProperties: type: string XML: type: object properties: name: type: string namespace: type: string format: uri prefix: type: string attribute: type: boolean default: false wrapped: type: boolean default: false patternProperties: '^x-': {} additionalProperties: false Response: type: object required: - description properties: description: type: string headers: type: object additionalProperties: oneOf: - $ref: '#/definitions/Header' - $ref: '#/definitions/Reference' content: type: object additionalProperties: $ref: '#/definitions/MediaType' links: type: object additionalProperties: oneOf: - $ref: '#/definitions/Link' - $ref: '#/definitions/Reference' patternProperties: '^x-': {} additionalProperties: false MediaType: type: object properties: schema: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' example: {} examples: type: object additionalProperties: oneOf: - $ref: '#/definitions/Example' - $ref: '#/definitions/Reference' encoding: type: object additionalProperties: $ref: '#/definitions/Encoding' patternProperties: '^x-': {} additionalProperties: false allOf: - $ref: '#/definitions/ExampleXORExamples' Example: type: object properties: summary: type: string description: type: string value: {} externalValue: type: string format: uri-reference patternProperties: '^x-': {} additionalProperties: false Header: type: object properties: description: type: string required: type: boolean default: false deprecated: type: boolean default: false allowEmptyValue: type: boolean default: false style: type: string enum: - simple default: simple explode: type: boolean allowReserved: type: boolean default: false schema: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' content: type: object additionalProperties: $ref: '#/definitions/MediaType' minProperties: 1 maxProperties: 1 example: {} examples: type: object additionalProperties: oneOf: - $ref: '#/definitions/Example' - $ref: '#/definitions/Reference' patternProperties: '^x-': {} additionalProperties: false allOf: - $ref: '#/definitions/ExampleXORExamples' - $ref: '#/definitions/SchemaXORContent' Paths: type: object patternProperties: '^\/': $ref: '#/definitions/PathItem' '^x-': {} additionalProperties: false PathItem: type: object properties: $ref: type: string summary: type: string description: type: string servers: type: array items: $ref: '#/definitions/Server' parameters: type: array items: oneOf: - $ref: '#/definitions/Parameter' - $ref: '#/definitions/Reference' uniqueItems: true patternProperties: '^(get|put|post|delete|options|head|patch|trace)$': $ref: '#/definitions/Operation' '^x-': {} additionalProperties: false Operation: type: object required: - responses properties: tags: type: array items: type: string summary: type: string description: type: string externalDocs: $ref: '#/definitions/ExternalDocumentation' operationId: type: string parameters: type: array items: oneOf: - $ref: '#/definitions/Parameter' - $ref: '#/definitions/Reference' uniqueItems: true requestBody: oneOf: - $ref: '#/definitions/RequestBody' - $ref: '#/definitions/Reference' responses: $ref: '#/definitions/Responses' callbacks: type: object additionalProperties: oneOf: - $ref: '#/definitions/Callback' - $ref: '#/definitions/Reference' deprecated: type: boolean default: false security: type: array items: $ref: '#/definitions/SecurityRequirement' servers: type: array items: $ref: '#/definitions/Server' patternProperties: '^x-': {} additionalProperties: false Responses: type: object properties: default: oneOf: - $ref: '#/definitions/Response' - $ref: '#/definitions/Reference' patternProperties: '^[1-5](?:\d{2}|XX)$': oneOf: - $ref: '#/definitions/Response' - $ref: '#/definitions/Reference' '^x-': {} minProperties: 1 additionalProperties: false SecurityRequirement: type: object additionalProperties: type: array items: type: string Tag: type: object required: - name properties: name: type: string description: type: string externalDocs: $ref: '#/definitions/ExternalDocumentation' patternProperties: '^x-': {} additionalProperties: false ExternalDocumentation: type: object required: - url properties: description: type: string url: type: string format: uri-reference patternProperties: '^x-': {} additionalProperties: false ExampleXORExamples: description: Example and examples are mutually exclusive not: required: [example, examples] SchemaXORContent: description: Schema and content are mutually exclusive, at least one is required not: required: [schema, content] oneOf: - required: [schema] - required: [content] description: Some properties are not allowed if content is present allOf: - not: required: [style] - not: required: [explode] - not: required: [allowReserved] - not: required: [example] - not: required: [examples] Parameter: type: object properties: name: type: string in: type: string description: type: string required: type: boolean default: false deprecated: type: boolean default: false allowEmptyValue: type: boolean default: false style: type: string explode: type: boolean allowReserved: type: boolean default: false schema: oneOf: - $ref: '#/definitions/Schema' - $ref: '#/definitions/Reference' content: type: object additionalProperties: $ref: '#/definitions/MediaType' minProperties: 1 maxProperties: 1 example: {} examples: type: object additionalProperties: oneOf: - $ref: '#/definitions/Example' - $ref: '#/definitions/Reference' patternProperties: '^x-': {} additionalProperties: false required: - name - in allOf: - $ref: '#/definitions/ExampleXORExamples' - $ref: '#/definitions/SchemaXORContent' - $ref: '#/definitions/ParameterLocation' ParameterLocation: description: Parameter location oneOf: - description: Parameter in path required: - required properties: in: enum: [path] style: enum: [matrix, label, simple] default: simple required: enum: [true] - description: Parameter in query properties: in: enum: [query] style: enum: [form, spaceDelimited, pipeDelimited, deepObject] default: form - description: Parameter in header properties: in: enum: [header] style: enum: [simple] default: simple - description: Parameter in cookie properties: in: enum: [cookie] style: enum: [form] default: form RequestBody: type: object required: - content properties: description: type: string content: type: object additionalProperties: $ref: '#/definitions/MediaType' required: type: boolean default: false patternProperties: '^x-': {} additionalProperties: false SecurityScheme: oneOf: - $ref: '#/definitions/APIKeySecurityScheme' - $ref: '#/definitions/HTTPSecurityScheme' - $ref: '#/definitions/OAuth2SecurityScheme' - $ref: '#/definitions/OpenIdConnectSecurityScheme' APIKeySecurityScheme: type: object required: - type - name - in properties: type: type: string enum: - apiKey name: type: string in: type: string enum: - header - query - cookie description: type: string patternProperties: '^x-': {} additionalProperties: false HTTPSecurityScheme: type: object required: - scheme - type properties: scheme: type: string bearerFormat: type: string description: type: string type: type: string enum: - http patternProperties: '^x-': {} additionalProperties: false oneOf: - description: Bearer properties: scheme: enum: [bearer] - description: Non Bearer not: required: [bearerFormat] properties: scheme: not: enum: [bearer] OAuth2SecurityScheme: type: object required: - type - flows properties: type: type: string enum: - oauth2 flows: $ref: '#/definitions/OAuthFlows' description: type: string patternProperties: '^x-': {} additionalProperties: false OpenIdConnectSecurityScheme: type: object required: - type - openIdConnectUrl properties: type: type: string enum: - openIdConnect openIdConnectUrl: type: string format: uri-reference description: type: string patternProperties: '^x-': {} additionalProperties: false OAuthFlows: type: object properties: implicit: $ref: '#/definitions/ImplicitOAuthFlow' password: $ref: '#/definitions/PasswordOAuthFlow' clientCredentials: $ref: '#/definitions/ClientCredentialsFlow' authorizationCode: $ref: '#/definitions/AuthorizationCodeOAuthFlow' patternProperties: '^x-': {} additionalProperties: false ImplicitOAuthFlow: type: object required: - authorizationUrl - scopes properties: authorizationUrl: type: string format: uri-reference refreshUrl: type: string format: uri-reference scopes: type: object additionalProperties: type: string patternProperties: '^x-': {} additionalProperties: false PasswordOAuthFlow: type: object required: - tokenUrl properties: tokenUrl: type: string format: uri-reference refreshUrl: type: string format: uri-reference scopes: type: object additionalProperties: type: string patternProperties: '^x-': {} additionalProperties: false ClientCredentialsFlow: type: object required: - tokenUrl properties: tokenUrl: type: string format: uri-reference refreshUrl: type: string format: uri-reference scopes: type: object additionalProperties: type: string patternProperties: '^x-': {} additionalProperties: false AuthorizationCodeOAuthFlow: type: object required: - authorizationUrl - tokenUrl properties: authorizationUrl: type: string format: uri-reference tokenUrl: type: string format: uri-reference refreshUrl: type: string format: uri-reference scopes: type: object additionalProperties: type: string patternProperties: '^x-': {} additionalProperties: false Link: type: object properties: operationId: type: string operationRef: type: string format: uri-reference parameters: type: object additionalProperties: {} requestBody: {} description: type: string server: $ref: '#/definitions/Server' patternProperties: '^x-': {} additionalProperties: false not: description: Operation Id and Operation Ref are mutually exclusive required: [operationId, operationRef] Callback: type: object additionalProperties: $ref: '#/definitions/PathItem' patternProperties: '^x-': {} Encoding: type: object properties: contentType: type: string headers: type: object additionalProperties: $ref: '#/definitions/Header' style: type: string enum: - form - spaceDelimited - pipeDelimited - deepObject explode: type: boolean allowReserved: type: boolean default: false additionalProperties: false OpenAPI-Specification-3.1.0/scripts/000077500000000000000000000000001401301652500172105ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/scripts/yaml2json/000077500000000000000000000000001401301652500211265ustar00rootroot00000000000000OpenAPI-Specification-3.1.0/scripts/yaml2json/yaml2json.js000077500000000000000000000012021401301652500234000ustar00rootroot00000000000000#!/usr/bin/env node 'use strict'; const fs = require('fs'); const yaml = require('yaml'); function convert(filename) { console.log(filename); const s = fs.readFileSync(filename,'utf8'); let obj; try { obj = yaml.parse(s, {prettyErrors: true}); fs.writeFileSync(filename.replace('.yaml','.json'),JSON.stringify(obj,null,2),'utf8'); } catch (ex) { console.warn(' ',ex.message); process.exitCode = 1; } } if (process.argv.length<3) { console.warn('Usage: yaml2json {infiles}'); } else { for (let i=2;iResource: A `resource` in Swagger is an entity that has a set of exposed operations. The entity can represent an actual object (pets, users..) or a set of logical operations collated together. It is up to the specification user to decide whether sub-resources should be referred to as part of their main resource or as a resource of their own. For example, assume the following URL set: ``` - /users - GET POST - /users/{id} - GET PATCH DELETE ``` In this case, there's either one "/users" resource that contains operations on the "/users/{id}" sub-resource, or two separate resources. - URL: A fully qualified URL. ## 4. Specification ### 4.1 Format The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. For example, if a field is said to have an array value, the JSON array representation will be used: ```js { "field" : [...] } ``` Please note that while the API is described using JSON, the input and/or output can be in XML, YAML, plain text, or whichever format you chose to use with your API. Unless noted otherwise, all field names in the specification are **case sensitive**. ### 4.2 File Structure The Swagger representation of the API is comprised of two file types: 1. [**The Resource Listing**](#51-resource-listing) - This is the root document that contains general API information and lists the resources. Each resource has its own URL that defines the API operations on it. 1. [**The API Declaration**](#52-api-declaration) - This document describes a resource, including its API calls and models. There is one file per resource. ### 4.3 Data Types In the Swagger specification, the data types are used in several locations - [Operations](#523-operation-object), [Operation Parameters](#524-parameter-object), [Models](#527-model-object), and within the data types themselves (arrays). The fields used to describe a given data type are added flatly to the relevant object. For example, if an object Foo has the field `name`, and is also a data type, then it MUST also include the field `type` (or its variance, as explained ahead). In this example, Foo would look like: ```js "Foo" : { "name" : "sample", "type" : "string", ... } ``` This section describes the general fields that are available to describe such data types. Some data types allow additional fields to extend further limitations on the data type *value* (see [4.3.3 Data Type Fields](#433-data-type-fields) for further details). Special care should be taken when referencing a model (or a complex type). There are currently two variations, and the proper variation should be documented everywhere the model may be used. This behavior will be unified in future versions of the spec. The Swagger specification supports five data types: 1. [`primitive`](#431-primitives) (input/output) 1. containers (as arrays/sets) (input/output) 1. [complex](#527-model-object) (as `models`) (input/output) 1. [`void`](#432-void) (output) 1. [`File`](#434-file) (input) #### 4.3.1 Primitives Different programming languages represent primitives differently. The Swagger specification supports by name only the primitive types supported by the [JSON-Schema Draft 4](http://json-schema.org/latest/json-schema-core.html#anchor8). However, in order to allow fine tuning a primitive definition, an additional [`format`](#dataTypeFormat) field MAY accompany the [`type`](#dataTypeType) primitive to give more information about the type used. If the [`format`](#dataTypeFormat) field is used, the respective client MUST conform to the elaborate type. Common Name | [`type`](#dataTypeType) | [`format`](#dataTypeFormat) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits long | `integer` | `int64` | signed 64 bits float | `number` | `float` | double | `number` | `double` | string | `string` | | byte | `string` | `byte` | boolean | `boolean` | | date | `string` | `date` | dateTime | `string` | `date-time` | #### 4.3.2 `void` This value type is used to indicate that an [operation](#523-operation-object) returns no value. As such it MAY be used only for the return type of operations. #### 4.3.3 Data Type Fields As explained above, when an object is said to include a data type, there are a set of fields it may include (some are required and some are optional). Special care should be taken when referencing a model (or a complex type). There currently two variations, and the proper variation should be documented everywhere it may be used. This behavior will be unified in future versions of the spec. The table below shows the available fields to describe a data type. The `Validity` column may impose additional restrictions as to which data type is required in order to include this field. For example, [`enum`](#dataTypeEnum) may only be included if the [`type`](#dataTypeType) field is set to `string`. Field Name | Type | Validity |Description ---|:---:|---|--- type | `string` | Any |**Required (if [`$ref`](#dataTypeRef) is not used).** The return type of the operation. The value MUST be one of the [Primitives](#431-primitives), `array` or a model's [`id`](#modelId). $ref | `string` | Any | **Required (if [`type`](#dataTypeType) is not used).** The [Model](#527-model-object) to be used. The value MUST be a model's [`id`](#modelId). format | `string` | primitive | Fine-tuned primitive type definition. See [Primitives](#431-primitives) for further information. The value MUST be one that is defined under [Primitives](#431-primitives), corresponding to the right primitive [`type`](#dataTypeType). defaultValue | *special* | primitive | The default value to be used for the field. The value type MUST conform with the primitive's [`type`](#dataTypeType) value. enum | [`string`] | `string` | A fixed list of possible values. If this field is used in conjunction with the [`defaultValue`](#dataTypeDefaultValue) field, then the default value MUST be one of the values defined in the `enum`. minimum | `string` | `number`, `integer` | The minimum valid value for the type, inclusive. If this field is used in conjunction with the [`defaultValue`](#dataTypeDefaultValue) field, then the default value MUST be higher than or equal to this value. The value type is `string` and should represent the minimum numeric value. **Note**: This will change to a numeric value in the future. maximum | `string` | `number`, `integer` | The maximum valid value for the type, inclusive. If this field is used in conjunction with the [`defaultValue`](#dataTypeDefaultValue) field, then the default value MUST be lower than or equal to this value. The value type is `string` and should represent the maximum numeric value. **Note**: This will change to a numeric value in the future. items | [Items Object](#434-items-object) | `array` | **Required.** The type definition of the values in the container. A container MUST NOT be nested in another container. uniqueItems | `boolean` | `array` | A flag to note whether the container allows duplicate values or not. If the value is set to `true`, then the `array` acts as a set. #### 4.3.4 Items Object This object is used to describe the value types used inside an array. Of the [Data Type Fields](#433-data-type-fields), it can include either the [`type`](#dataTypeType) and [`format`](#dataTypeFormat) fields *OR* the [`$ref`](#dataTypeRef) field (when referencing a model). The rest of the listed Data Type fields are not applicable. If the [`type`](#dataTypeType) field is included it MUST NOT have the value `array`. There's currently no support for containers within containers. ##### 4.3.4.1 Object Examples For a primitive type: ```js { "type": "string" } ``` For a complex type (model): ```js { "$ref": "Pet" } ``` #### 4.3.5 `File` The `File` (case sensitive) is a special type used to denote file upload. Note that declaring a model with the name `File` may lead to various conflicts with third party tools and SHOULD be avoided. When using `File`, the [`consumes`](#operationConsumes) field MUST be `"multipart/form-data"`, and the [`paramType`](#parameterParamType) MUST be `"form"`. ## 5. Schema ### 5.1 Resource Listing The Resource Listing serves as the root document for the API description. It contains general information about the API and an inventory of the available resources. By default, this document SHOULD be served at the `/api-docs` path. Field Name | Type | Description ---|:---:|--- swaggerVersion | `string` | **Required.** Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be an existing Swagger specification version.
Currently, `"1.0"`, `"1.1"`, `"1.2"` are valid values. The field is a `string` type for possible non-numeric versions in the future (for example, "1.2a"). apis | [ [Resource Object](#512-resource-object) ] | **Required.** Lists the resources to be described by this specification implementation. The array can have 0 or more elements. apiVersion| `string` | Provides the version of the application API (not to be confused by the [specification version](#rlSwaggerVersion)). info | [Info Object](#513-info-object) | Provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience. authorizations | [Authorizations Object](#514-authorizations-object) | Provides information about the authorization schemes allowed on this API. #### 5.1.1 Object Example ```js { "apiVersion": "1.0.0", "swaggerVersion": "1.2", "apis": [ { "path": "/pet", "description": "Operations about pets" }, { "path": "/user", "description": "Operations about user" }, { "path": "/store", "description": "Operations about store" } ], "authorizations": { "oauth2": { "type": "oauth2", "scopes": [ { "scope": "email", "description": "Access to your email address" }, { "scope": "pets", "description": "Access to your pets" } ], "grantTypes": { "implicit": { "loginEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" }, "tokenName": "access_token" }, "authorization_code": { "tokenRequestEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" }, "tokenEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } } } } }, "info": { "title": "Swagger Sample App", "description": "This is a sample server Petstore server. You can find out more about Swagger \n at http://swagger.wordnik.com or on irc.freenode.net, #swagger. For this sample,\n you can use the api key \"special-key\" to test the authorization filters", "termsOfServiceUrl": "http://swagger.io/terms/", "contact": "apiteam@wordnik.com", "license": "Apache 2.0", "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html" } } ``` #### 5.1.2 Resource Object The Resource object describes a [resource](#definitionResource) API endpoint in the application. Field Name | Type | Description ---|:---:|--- path | `string` | **Required.** A relative path to the [API declaration](#52-api-declaration) from the path used to retrieve this Resource Listing. This `path` does not necessarily have to correspond to the URL which actually serves this resource in the API but rather where the resource listing itself is served. The value SHOULD be in a relative (URL) path format. description | `string` | *Recommended.* A short description of the resource. ##### 5.1.2.1 Object Example: ```js { "path": "/pets", "description": "Operations about pets." } ``` #### 5.1.3 Info Object The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience. Field Name | Type | Description ---|:---:|--- title | `string` | **Required.** The title of the application. description | `string` | **Required.** A short description of the application. termsOfServiceUrl | `string` | A URL to the Terms of Service of the API. contact | `string` | An email to be used for API-related correspondence. license | `string` | The license name used for the API. licenseUrl | `string` | A URL to the license used for the API. ##### 5.1.3.1 Object Example: ```js { "title": "Swagger Sample App", "description": "This is a sample server Petstore server.", "termsOfServiceUrl": "http://swagger.io/terms/", "contact": "apiteam@wordnik.com", "license": "Apache 2.0", "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html" } ``` #### 5.1.4 Authorizations Object The object provides information about the authorization schemes provided on this API. Currently, Swagger supports three authorization schemes - basic authentication, API key and OAuth2. The Authorizations Object is used only to *declare* the available authorization schemes but not say which are required where. The actual authorization restrictions are done at the [API declaration](#52-api-declaration) level. Please note that the Authorizations Object is an object containing other object definitions and as such is structured as follows: ```js { "Authorization1" : {...}, "Authorization2" : {...}, ..., "AuthorizationN" : {...} } ``` Field Name | Type | Description ---|:---:|--- {Authorization Name} | [Authorization Object](#515-authorization-object) | A new authorization definition. The name given to the {Authorization Name} is a friendly name that should be used when referring to the authorization scheme. In many cases, the {Authorization Name} used is the same as its type, but it can be anything. ##### 5.1.4.1 Object Example: ```js { "oauth2": { "type": "oauth2", "scopes": [ { "scope": "email", "description": "Access to your email address" }, { "scope": "pets", "description": "Access to your pets" } ], "grantTypes": { "implicit": { "loginEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" }, "tokenName": "access_token" }, "authorization_code": { "tokenRequestEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" }, "tokenEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } } } } } ``` #### 5.1.5 Authorization Object The object provides information about a specific authorization scheme. Currently, the authorization schemes supported are basic authentication, API key and OAuth2. Within OAuth2, the Authorization Code Grant and Implicit Grant are supported. In the table below, the `Validity` column imposes additional limitations to the requirement of the [`type`](#authorizationType) in order to be able to use that field. Field Name | Type | Validity | Description ---|:---:|---|--- type | `string` | Any | **Required.** The type of the authorization scheme. Values MUST be either `"basicAuth"`, `"apiKey"` or `"oauth2"`. passAs | `string` | `apiKey` | **Required.** Denotes how the API key must be passed. Valid values are `"header"` or `"query"`. keyname | `string` | `apiKey` | **Required.** The name of the `header` or `query` parameter to be used when passing the API key. scopes | [[Scope Object](#516-scope-object)] | `oauth2` | A list of supported OAuth2 scopes. grantTypes | [Grant Types Object](#517-grant-types-object) | `oauth2` | **Required.** Detailed information about the grant types supported by the OAuth2 authorization scheme. ##### 5.1.5.1 Object Example: ```js "oauth2": { "type": "oauth2", "scopes": [ { "scope": "email", "description": "Access to your email address" }, { "scope": "pets", "description": "Access to your pets" } ], "grantTypes": { "implicit": { "loginEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" }, "tokenName": "access_token" }, "authorization_code": { "tokenRequestEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" }, "tokenEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } } } } ``` #### 5.1.6 Scope Object Describes an OAuth2 authorization scope. Field Name | Type | Description ---|:---:|--- scope | `string` | **Required.** The name of the scope. description | `string` | *Recommended.* A short description of the scope. ##### 5.1.6.1 Object Example: ```js { "scope": "email", "description": "Access to your email address" } ``` #### 5.1.7 Grant Types Object Provides details regarding the OAuth2 grant types that are supported by the API. Currently, the Authorization Code and Implicit grants are supported. At least one of the grant types MUST be included (otherwise there's no need for the OAuth2 declaration). Field Name | Type | Description ---|:---:|--- implicit | [Implicit Object](#518-implicit-object) | The Implicit Grant flow definition. authorization_code | [Authorization Code Object](#519-authorization-code-object) | The Authorization Code Grant flow definition. ##### 5.1.7.1 Object Example: ```js { "implicit": { "loginEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" }, "tokenName": "access_token" }, "authorization_code": { "tokenRequestEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" }, "tokenEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } } } ``` #### 5.1.8 Implicit Object Provides details regarding the OAuth2's Implicit Grant flow type. Field Name | Type | Description ---|:---:|--- loginEndpoint | [Login Endpoint Object](#5110-login-endpoint-object) | **Required.** The login endpoint definition. tokenName | `string` | An optional alternative name to standard "access_token" OAuth2 parameter. ##### 5.1.8.1 Object Example: ```js { "loginEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" }, "tokenName": "access_token" } ``` #### 5.1.9 Authorization Code Object Provides details regarding the OAuth2's Authorization Code Grant flow type. Field Name | Type | Description ---|:---:|--- tokenRequestEndpoint | [Token Request Endpoint Object](#5111-token-request-endpoint-object) | **Required.** The token request endpoint definition. tokenEndpoint | [Token Endpoint Object](#5112-token-endpoint-object) | **Required.** The token endpoint definition. ##### 5.1.9.1 Object Example: ```js { "tokenRequestEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" }, "tokenEndpoint": { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } } ``` #### 5.1.10 Login Endpoint Object Provides details regarding the Implicit Grant's *authorization endpoint*. Field Name | Type | Description ---|:---:|--- url | `string` | **Required.** The URL of the authorization endpoint for the implicit grant flow. The value SHOULD be in a URL format. ##### 5.1.10.1 Object Example: ```js { "url": "http://petstore.swagger.wordnik.com/oauth/dialog" } ``` #### 5.1.11 Token Request Endpoint Object Provides details regarding the OAuth2's *Authorization Endpoint*. Field Name | Type | Description ---|:---:|--- url | `string` | **Required.** The URL of the authorization endpoint for the authentication code grant flow. The value SHOULD be in a URL format. clientIdName | `string` | An optional alternative name to standard "client_id" OAuth2 parameter. clientSecretName | `string` | An optional alternative name to the standard "client_secret" OAuth2 parameter. ##### 5.1.11.1 Object Example: ```js { "url": "http://petstore.swagger.wordnik.com/oauth/requestToken", "clientIdName": "client_id", "clientSecretName": "client_secret" } ``` #### 5.1.12 Token Endpoint Object Provides details regarding the OAuth2's *Token Endpoint*. Field Name | Type | Description ---|:---:|--- url | `string` | **Required.** The URL of the token endpoint for the authentication code grant flow. The value SHOULD be in a URL format. tokenName | `string` | An optional alternative name to standard "access_token" OAuth2 parameter. ##### 5.1.12.1 Object Example: ```js { "url": "http://petstore.swagger.wordnik.com/oauth/token", "tokenName": "access_code" } ``` ### 5.2 API Declaration The API Declaration provides information about an API exposed on a resource. There should be one file per [Resource](#512-resource-object) described. The file MUST be served in the URL described by the [`path`](#aePath) field. Field Name | Type | Description ---|:---:|--- swaggerVersion | `string` | **Required.** Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be an existing Swagger specification version.
Currently, `"1.0"`, `"1.1"`, `"1.2"` are valid values. apiVersion | `string` | Provides the version of the application API (not to be confused by the [specification version](#adSwaggerVersion)). basePath | `string` | **Required.** The root URL serving the API. This field is important because while it is common to have the Resource Listing and API Declarations on the server providing the APIs themselves, it is not a requirement. The API specifications can be served using static files and not generated by the API server itself, so the URL for serving the API cannot always be derived from the URL serving the API specification. The value SHOULD be in the format of a URL. resourcePath | `string` | The *relative* path to the resource, from the [`basePath`](#adBasePath), which this API Specification describes. The value MUST precede with a forward slash (`"/"`). apis | [[API Object](#522-api-object)] | **Required.** A list of the APIs exposed on this resource. There MUST NOT be more than one API Object per [`path`](#apiPath) in the array. models | [Models Object](#526-models-object) | A list of the models available to this resource. Note that these need to be exposed separately for each API Declaration. produces | [`string`] | A list of MIME types the APIs on this resource can produce. This is global to all APIs but can be overridden on specific API calls. consumes | [`string`] | A list of MIME types the APIs on this resource can consume. This is global to all APIs but can be overridden on specific API calls. authorizations | [Authorizations Object](#5210-authorizations-object) | A list of authorizations schemes *required* for the operations listed in this API declaration. Individual operations may override this setting. If there are multiple authorization schemes described here, it means they're **all** applied. #### 5.2.1 Object Example ```js { "apiVersion": "1.0.0", "swaggerVersion": "1.2", "basePath": "http://petstore.swagger.wordnik.com/api", "resourcePath": "/store", "produces": [ "application/json" ], "authorizations": {}, "apis": [ { "path": "/store/order/{orderId}", "operations": [ { "method": "GET", "summary": "Find purchase order by ID", "notes": "For valid response try integer IDs with value <= 5. Anything above 5 or nonintegers will generate API errors", "type": "Order", "nickname": "getOrderById", "authorizations": {}, "parameters": [ { "name": "orderId", "description": "ID of pet that needs to be fetched", "required": true, "type": "string", "paramType": "path" } ], "responseMessages": [ { "code": 400, "message": "Invalid ID supplied" }, { "code": 404, "message": "Order not found" } ] }, { "method": "DELETE", "summary": "Delete purchase order by ID", "notes": "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors", "type": "void", "nickname": "deleteOrder", "authorizations": { "oauth2": [ { "scope": "test:anything", "description": "anything" } ] }, "parameters": [ { "name": "orderId", "description": "ID of the order that needs to be deleted", "required": true, "type": "string", "paramType": "path" } ], "responseMessages": [ { "code": 400, "message": "Invalid ID supplied" }, { "code": 404, "message": "Order not found" } ] } ] }, { "path": "/store/order", "operations": [ { "method": "POST", "summary": "Place an order for a pet", "notes": "", "type": "void", "nickname": "placeOrder", "authorizations": { "oauth2": [ { "scope": "test:anything", "description": "anything" } ] }, "parameters": [ { "name": "body", "description": "order placed for purchasing the pet", "required": true, "type": "Order", "paramType": "body" } ], "responseMessages": [ { "code": 400, "message": "Invalid order" } ] } ] } ], "models": { "Order": { "id": "Order", "properties": { "id": { "type": "integer", "format": "int64" }, "petId": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "format": "int32" }, "status": { "type": "string", "description": "Order Status", "enum": [ "placed", "approved", "delivered" ] }, "shipDate": { "type": "string", "format": "date-time" } } } } } ``` #### 5.2.2 API Object The API Object describes one or more operations on a single [`path`](#apiPath). In the [`apis`](#adApis) array, there MUST be only one [`API Object`](#522-api-object) per [`path`](#apiPath). Field Name | Type | Description ---|:---:|--- path | `string` | **Required.** The relative path to the operation, from the [`basePath`](#adBasePath), which this operation describes. The value SHOULD be in a relative (URL) path format. description | `string` | *Recommended.* A short description of the resource. operations | [[Operation Object](#523-operation-object)] | **Required.** A list of the API operations available on this path. The array may include 0 or more operations. There MUST NOT be more than one Operation Object per [`method`](#operationMethod) in the array. ##### 5.2.2.1 Object Example: ```js { "path": "/pet", "operations": [ { "method": "PUT", "summary": "Update an existing pet", "notes": "", "type": "void", "nickname": "updatePet", "authorizations": {}, "parameters": [ { "name": "body", "description": "Pet object that needs to be updated in the store", "required": true, "type": "Pet", "paramType": "body" } ], "responseMessages": [ { "code": 400, "message": "Invalid ID supplied" }, { "code": 404, "message": "Pet not found" }, { "code": 405, "message": "Validation exception" } ] }, { "method": "POST", "summary": "Add a new pet to the store", "notes": "", "type": "void", "nickname": "addPet", "consumes": [ "application/json", "application/xml" ], "authorizations": { "oauth2": [ { "scope": "test:anything", "description": "anything" } ] }, "parameters": [ { "name": "body", "description": "Pet object that needs to be added to the store", "required": true, "type": "Pet", "paramType": "body" } ], "responseMessages": [ { "code": 405, "message": "Invalid input" } ] } ] } ``` #### 5.2.3 Operation Object The Operation Object describes a single operation on a [`path`](#apiPath). In the [`operations`](#apiOperations) array, there MUST be only one [`Operation Object`](#523-operation-object) per [`method`](#operationMethod). This object includes the [Data Type Fields](#433-data-type-fields) in order to describe the return value of the operation. The [`type`](#dataTypeType) field MUST be used to link to other models. This is the only object where the [`type`](#dataTypeType) MAY have the value of [`void`](#432-void) to indicate that the operation returns no value. Field Name | Type | Description ---|:---:|--- method | `string` | **Required.** The HTTP method required to invoke this operation. The value MUST be one of the following values: `"GET"`, `"HEAD"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`, `"OPTIONS"`. The values MUST be in uppercase. summary | `string` | A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters. notes | `string` | A verbose explanation of the operation behavior. nickname |`string` | **Required.** A unique id for the operation that can be used by tools reading the output for further and easier manipulation. For example, Swagger-Codegen will use the nickname as the method name of the operation in the client it generates. The value MUST be alphanumeric and may include underscores. Whitespace characters are not allowed. authorizations | [Authorizations Object](#5210-authorizations-object) | A list of authorizations required to execute this operation. While not mandatory, if used, it overrides the value given at the API Declaration's [authorizations](#adAuthorizations). In order to completely remove API Declaration's authorizations completely, an empty object (`{}`) may be applied. parameters | [[Parameter Object](#524-parameter-object)] | **Required.** The inputs to the operation. If no parameters are needed, an empty array MUST be included. responseMessages | [[Response Message Object](#525-response-message-object)] | Lists the possible response statuses that can return from the operation. produces | [`string`] | A list of MIME types this operation can produce. This is overrides the global [`produces`](#adProduces) definition at the root of the API Declaration. Each `string` value SHOULD represent a MIME type. consumes | [`string`] | A list of MIME types this operation can consume. This is overrides the global [`consumes`](#adConsumes) definition at the root of the API Declaration. Each `string` value SHOULD represent a MIME type. deprecated | `string` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Valid value MUST be either `"true"` or `"false"`. *Note:* This field will change to type `boolean` in the future. ##### 5.2.3.1 Object Example ````js { "method": "GET", "summary": "Find pet by ID", "notes": "Returns a pet based on ID", "type": "Pet", "nickname": "getPetById", "authorizations": {}, "parameters": [ { "name": "petId", "description": "ID of pet that needs to be fetched", "required": true, "type": "integer", "format": "int64", "paramType": "path", "minimum": "1.0", "maximum": "100000.0" } ], "responseMessages": [ { "code": 400, "message": "Invalid ID supplied" }, { "code": 404, "message": "Pet not found" } ] } ```` #### 5.2.4 Parameter Object The Parameter Object describes a single parameter to be sent in an operation and maps to the [`parameters`](#operationParameters) field in the [Operation Object](#523-operation-object). This object includes the [Data Type Fields](#433-data-type-fields) in order to describe the type of this parameter. The [`type`](#dataTypeType) field MUST be used to link to other models. If [`type`](#dataTypeType) is [`File`](#434-file), the [`consumes`](#operationConsumes) field MUST be `"multipart/form-data"`, and the [`paramType`](#parameterParamType) MUST be `"form"`. Field Name | Type | Description ---|:---:|--- paramType | `string` | **Required.** The type of the parameter (that is, the location of the parameter in the request). The value MUST be one of these values: `"path"`, `"query"`, `"body"`, `"header"`, `"form"`. Note that the values MUST be lower case. name | `string` | **Required.** The unique name for the parameter. Each `name` MUST be unique, even if they are associated with different `paramType` values. Parameter names are *case sensitive*.
  • If [`paramType`](#parameterParamType) is `"path"`, the `name` field MUST correspond to the associated path segment from the [`path`](#apiPath) field in the [API Object](#522-api-object).
  • If [`paramType`](#parameterParamType) is `"query"`, the `name` field corresponds to the query parameter name.
  • If [`paramType`](#parameterParamType) is `"body"`, the name is used only for Swagger-UI and Swagger-Codegen. In this case, the `name` MUST be `"body"`.
  • If [`paramType`](#parameterParamType) is `"form"`, the `name` field corresponds to the form parameter key.
  • If [`paramType`](#parameterParamType) is `"header"`, the `name` field corresponds to the header parameter key.
See [here](#5241-name-examples) for some examples. description | `string` | *Recommended.* A brief description of this parameter. required | `boolean` | A flag to note whether this parameter is required. If this field is not included, it is equivalent to adding this field with the value `false`. If [`paramType`](#parameterParamType) is `"path"` then this field MUST be included and have the value `true`. allowMultiple | `boolean` | Another way to allow multiple values for a "query" parameter. If used, the query parameter may accept comma-separated values. The field may be used only if [`paramType`](#parameterParamType) is `"query"`, `"header"` or `"path"`. ##### 5.2.4.1 Name Examples - If [`paramType`](#parameterParamType) is `"path"`, and assuming the `path` is `"/pet/{id}"`: ```js "name": "id" ``` - If [`paramType`](#parameterParamType) is `"query"`, and assuming the URL call is `"http://host/resource?limit=100"` (that is, there's a query parameter called `"limit"`): ```js "name": "limit" ``` - If [`paramType`](#parameterParamType) is `"body"`: ```js "name": "body" ``` ##### 5.2.4.2 Object Example ```js { "name": "body", "description": "Pet object that needs to be updated in the store", "required": true, "type": "Pet", "paramType": "body" } ``` #### 5.2.5 Response Message Object The Response Message Object describes a single possible response message that can be returned from the operation call, and maps to the [`responseMessages`](#operationResponseMessages) field in the [Operation Object](#523-operation-object). Each Response Message allows you to give further details as to why the HTTP status code may be received. Field Name | Type | Description | ---|:---:|--- code | `integer` | **Required.** The HTTP status code returned. The value SHOULD be one of the status codes as described in [RFC 2616 - Section 10](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). message | `string` | **Required.** The explanation for the status code. It SHOULD be the reason an error is received if an error status code is used. responseModel | `string` | The return type for the given response. ##### 5.2.5.1 Object Example ```js { "code": 404, "message": "no project found", "responseModel": "ErrorModel" } ``` #### 5.2.6 Models Object The Models Object holds a field per model definition, and this is different than the structure of the other objects in the spec. It follows a subset of the [JSON-Schema](http://json-schema.org/) specification. Please note that the Models Object is an object containing other object definitions and as such is structured as follows: ```js { "Model1" : {...}, "Model2" : {...}, ..., "ModelN" : {...} } ``` Field Name | Type | Description ---|:---:|--- {Model Name} | [Model Object](#527-model-object) | A new model definition. Note the actual name of the field is the name you're giving your model. For example, "Category", "Pet", "User". ##### 5.2.6.1 Object Example ```js { "Category": { "id": "Category", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } } ``` #### 5.2.7 Model Object A Model Object holds the definition of a new model for this API Declaration. Models in Swagger allow for inheritance. The inheritance is controlled by two fields - [`subTypes`](#modelSubTypes) to give the name of the models extending this definition, and [`discriminator`](#modelDiscriminator) to support polymorphism. Field Name | Type | Description ---|:---:|--- id | `string` | **Required.** A unique identifier for the model. This MUST be the name given to [{Model Name}](#modelsModelname). description | `string` | A brief description of this model. required | [`string`] | A definition of which properties MUST exist when a model instance is produced. The values MUST be the [`{Property Name}`](#propertiesPropertyName) of one of the [`properties`](#528-properties-object). properties | [Properties Object](#528-properties-object) | **Required.** A list of properties (fields) that are part of the model subTypes | [`string`] | List of the [model `id`s](#modelId) that inherit from this model. Sub models inherit all the properties of the parent model. Since inheritance is transitive, if the parent of a model inherits from another model, its sub-model will include all properties. As such, if you have `Foo->Bar->Baz`, then Baz will inherit the properties of Bar and Foo. There MUST NOT be a cyclic definition of inheritance. For example, if `Foo -> ... -> Bar`, having `Bar -> ... -> Foo` is not allowed. There also MUST NOT be a case of multiple inheritance. For example, `Foo -> Baz <- Bar` is not allowed. A sub-model definition MUST NOT override the [`properties`](#modelProperties) of any of its ancestors. All sub-models MUST be defined in the same [API Declaration](#52-api-declaration). discriminator | `string` | MUST be included only if [`subTypes`](#modelSubTypes) is included. This field allows for polymorphism within the described inherited models. This field MAY be included at any base model but MUST NOT be included in a sub-model. The value of this field MUST be a name of one of the [`properties`](#modelProperties) in this model, and that field MUST be in the [`required`](#modelRequired) list. When used, the value of the *discriminator property* MUST be the name of the parent model or any of its sub-models (to any depth of inheritance). ##### 5.2.7.1 Object Example ```js { "id": "Order", "properties": { "id": { "type": "integer", "format": "int64" }, "petId": { "type": "integer", "format": "int64" }, "quantity": { "type": "integer", "format": "int32" }, "status": { "type": "string", "description": "OrderStatus", "enum": [ "placed", "approved", "delivered" ] }, "shipDate": { "type": "string", "format": "date-time" } } } ``` ##### 5.2.7.2 Inheritance Example Say we have a general Animal model, and a sub-model for Cat. ```js "Animal": { "id": "Animal", "required": [ "id", "type" ], "properties": { "id": { "type": "long" }, "type": { "type": "string" } }, "subTypes": ["Cat"], "discriminator": "type" }, "Cat": { "id": "Cat", "required": [ "likesMilk" ], "properties": { "likesMilk": { "type": "boolean" } }, } ``` #### 5.2.8 Properties Object The Properties Object holds a field per property definition, and this is different than the structure of the other objects in the spec. It follows a subset of the [JSON-Schema](http://json-schema.org/) specification. Please note that the Properties Object is an object containing other object definitions and as such is structured as follows: ```js { "Property1" : {...}, "Property2" : {...}, ..., "PropertyN" : {...} } ``` Field Name | Type | Description ---|:---:|--- {Property Name} | [Property Object](#529-property-object) | A new model property definition. Note the actual name of the field is the name you're giving your property. For example, "id", "name", "age". ##### 5.2.8.1 Object Example ```js { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } ``` #### 5.2.9 Property Object A Property Object holds the definition of a new property for a model. This object includes the [Data Type Fields](#433-data-type-fields) in order to describe the type of this property. The [`$ref`](#dataTypeRef) field MUST be used when linking to other models. Properties MUST NOT contain other properties. If there's a need for an internal object hierarchy, additional models MUST be created and linked to a flat structure. Field Name | Type | Description ---|:---:|--- description | `string` | *Recommended.* A brief description of this property. ##### 5.2.9.1 Object Examples A simple 64bit integer field called "id", with a description and min/max values: ```js "id": { "type": "integer", "format": "int64", "description": "unique identifier for the pet", "minimum": "0.0", "maximum": "100.0" } ``` A "category" field of a Category model. ```js "category": { "$ref": "Category" } ``` A "tags" field of type array containing Tag models. ```js "tags": { "type": "array", "items": { "$ref": "Tag" } } ``` #### 5.2.10 Authorizations Object The Authorizations Object provides information about the authorization schemes enforced on this API. If used in the API Declaration's [authorizations](#adAuthorizations), it applies to all operations listed. If used in the Operation's [authorizations](#operationAuthorizations), it applies to the operation itself and may override the API Declaration's authorizations. If multiple authorization schemes are described, they are **all** required to perform the operations listed. Please note that the Authorizations Object is an object containing arrays of object definitions and as such is structured as follows: ```js { "Authorization1" : [...], "Authorization2" : [...], ..., "AuthorizationN" : [...] } ``` Field Name | Type | Description ---|:---:|--- {Authorization Name} | * | The authorization scheme to be used. The name given to the {Authorization Name} MUST be a friendly name that was given to an authorization scheme in the Resource Listing's [authorizations](#rlAuthorizations). If the friendly name describes an OAuth2 security scheme, the value should be of type \[[Scope Object](#5211-scope-object)\] (but may be an empty array to denote 'no scopes'). For all other authorization scheme types, the value MUST be an empty array. ##### 5.2.10 Object Example: ```js { "oauth2": [ { "scope": "write:pets", "description": "modify pets in your account" }, { "scope": "read:pets", "description": "read your pets" } ] } ``` #### 5.2.11 Scope Object Describes an OAuth2 authorization scope. The scope described here MUST be described in the respective friendly name definition of the security scheme in the Resource Listing's [authorizations](#rlAuthorizations). Field Name | Type | Description ---|:---:|--- scope | `string` | **Required.** The name of the scope. description | `string` | *Recommended.* A short description of the scope. ##### 5.2.11.1 Object Example: ```js { "scope": "email", "description": "Access to your email address" } ``` OpenAPI-Specification-3.1.0/versions/2.0.md000077500000000000000000002370101401301652500202200ustar00rootroot00000000000000# OpenAPI Specification ## (fka Swagger RESTful API Documentation Specification) #### Version 2.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt). The Swagger specification is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). ## Introductions Swagger™ is a project used to describe and document RESTful APIs. The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools. ## Revision History Version | Date | Notes --- | --- | --- 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification ## Definitions ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. ##### Mime Types Mime type definitions are spread across several resources. The mime type definitions should be in compliance with [RFC 6838](http://tools.ietf.org/html/rfc6838). Some examples of possible mime type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC 7231](http://tools.ietf.org/html/rfc7231#section-6) and in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification ### Format The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a Swagger specification file. For example, if a field is said to have an array value, the JSON array representation will be used: ```js { "field" : [...] } ``` While the API is described using JSON it does not impose a JSON input/output to the API itself. All field names in the specification are **case sensitive**. The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name. ### File Structure The Swagger representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions. By convention, the Swagger specification file is named `swagger.json`. ### Data Types Primitive data types in the Swagger Specification are based on the types supported by the [JSON-Schema Draft 4](https://tools.ietf.org/html/draft-zyp-json-schema-04#section-3.5). Models are described using the [Schema Object](#schemaObject) which is a subset of JSON Schema Draft 4. An additional primitive data type `"file"` is used by the [Parameter Object](#parameterObject) and the [Response Object](#responseObject) to set the parameter type or the response as being a file. Primitives have an optional modifier property `format`. Swagger uses several known formats to more finely define the data type being used. However, the `format` property is an open `string`-valued property, and can have any value to support documentation needs. Formats such as `"email"`, `"uuid"`, etc., can be used even though they are not defined by this specification. Types that are not accompanied by a `format` property follow their definition from the JSON Schema (except for `file` type which is defined above). The formats defined by the Swagger Specification are: Common Name | [`type`](#dataTypeType) | [`format`](#dataTypeFormat) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits long | `integer` | `int64` | signed 64 bits float | `number` | `float` | | double | `number` | `double` | | string | `string` | | | byte | `string` | `byte` | base64 encoded characters binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) password | `string` | `password` | Used to hint UIs the input needs to be obscured. ### Schema #### Swagger Object This is the root document object for the API specification. It combines what previously was the Resource Listing and API Declaration (version 1.2 and earlier) together into one document. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- swagger | `string` | **Required.** Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be `"2.0"`. info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. host | `string` | The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating). basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#swaggerHost). If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating). schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `schemes` is not included, the default scheme to be used is the one used to access the Swagger definition itself. consumes | [`string`] | A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Mime Types](#mimeTypes). produces | [`string`] | A list of MIME types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Mime Types](#mimeTypes). paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. definitions | [Definitions Object](#definitionsObject) | An object to hold data types produced and consumed by operations. parameters | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters that can be used across operations. This property *does not* define global parameters for all operations. responses | [Responses Definitions Object](#responsesDefinitionsObject) | An object to hold responses that can be used across operations. This property *does not* define global responses for all operations. securityDefinitions | [Security Definitions Object](#securityDefinitionsObject) | Security scheme definitions that can be used across the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. #### Info Object The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **Required.** The title of the application. description | `string` | A short description of the application. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. termsOfService | `string` | The Terms of Service for the API. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Info Object Example: ```js { "title": "Swagger Sample App", "description": "This is a sample server Petstore server.", "termsOfService": "http://swagger.io/terms/", "contact": { "name": "API Support", "url": "http://www.swagger.io/support", "email": "support@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Swagger Sample App description: This is a sample server Petstore server. termsOfService: http://swagger.io/terms/ contact: name: API Support url: http://www.swagger.io/support email: support@swagger.io license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Contact Object Example: ```js { "name": "API Support", "url": "http://www.swagger.io/support", "email": "support@swagger.io" } ``` ```yaml name: API Support url: http://www.swagger.io/support email: support@swagger.io ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The license name used for the API. url | `string` | A URL to the license used for the API. MUST be in the format of a URL. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### License Object Example: ```js { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } ``` ```yaml name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html ``` #### Paths Object Holds the relative paths to the individual endpoints. The path is appended to the [`basePath`](#swaggerBasePath) in order to construct the full URL. The Paths may be empty, due to [ACL constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is appended to the [`basePath`](#swaggerBasePath) in order to construct the full URL. [Path templating](#pathTemplating) is allowed. ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Paths Object Example ```js { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "produces": [ "application/json" ], "responses": { "200": { "description": "A list of pets.", "schema": { "type": "array", "items": { "$ref": "#/definitions/pet" } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to produces: - application/json responses: '200': description: A list of pets. schema: type: array items: $ref: '#/definitions/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item may be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. 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 [Swagger Object's parameters](#swaggerParameters). There can be one "body" parameter at most. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Path Item Object Example ```js { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "produces": [ "application/json", "text/html" ], "responses": { "200": { "description": "pet response", "schema": { "type": "array", "items": { "$ref": "#/definitions/Pet" } } }, "default": { "description": "error payload", "schema": { "$ref": "#/definitions/ErrorModel" } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "type": "array", "items": { "type": "string" }, "collectionFormat": "csv" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById produces: - application/json - text/html responses: '200': description: pet response schema: type: array items: $ref: '#/definitions/Pet' default: description: error payload schema: $ref: '#/definitions/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true type: array items: type: string collectionFormat: csv ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters. description | `string` | A verbose explanation of the operation behavior. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions. consumes | [`string`] | A list of MIME types the operation can consume. This overrides the [`consumes`](#swaggerConsumes) definition at the Swagger Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes). produces | [`string`] | A list of MIME types the operation can produce. This overrides the [`produces`](#swaggerProduces) definition at the Swagger Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes). 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 [Swagger Object's parameters](#swaggerParameters). There can be one "body" parameter at most. responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation. schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the Swagger Object [`schemes`](#swaggerSchemes) definition. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level [`security`](#swaggerSecurity). To remove a top-level security declaration, an empty array can be used. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Operation Object Example ```js { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "description": "", "operationId": "updatePetWithForm", "consumes": [ "application/x-www-form-urlencoded" ], "produces": [ "application/json", "application/xml" ], "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "type": "string" }, { "name": "name", "in": "formData", "description": "Updated name of the pet", "required": false, "type": "string" }, { "name": "status", "in": "formData", "description": "Updated status of the pet", "required": false, "type": "string" } ], "responses": { "200": { "description": "Pet updated." }, "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data description: "" operationId: updatePetWithForm consumes: - application/x-www-form-urlencoded produces: - application/json - application/xml parameters: - name: petId in: path description: ID of pet that needs to be updated required: true type: string - name: name in: formData description: Updated name of the pet required: false type: string - name: status in: formData description: Updated status of the pet required: false type: string responses: '200': description: Pet updated. '405': description: Invalid input security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### External Documentation Object Example ```js { "description": "Find more info here", "url": "https://swagger.io" } ``` ```yaml description: Find more info here url: https://swagger.io ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). There are five possible parameter types. * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * Header - Custom headers that are expected as part of the request. * Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation. * Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in Swagger's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4): * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred. * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*.
  • 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.
  • For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.
in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "body". description | `string` | A brief description of the parameter. This could contain examples of use. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. If [`in`](#parameterIn) is `"body"`: Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | **Required.** The schema defining the type used for the body parameter. If [`in`](#parameterIn) is any value other than `"body"`: Field Name | Type | Description ---|:---:|--- type | `string` | **Required.** The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"` or `"file"`. If `type` is `"file"`, the [`consumes`](#operationConsumes) MUST be either `"multipart/form-data"`, `" application/x-www-form-urlencoded"` or both and the parameter MUST be [`in`](#parameterIn) `"formData"`. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for either `query` or `formData` parameters and allows you to send a parameter with a name only or an empty value. Default value is `false`. items | [Items Object](#itemsObject) | **Required if [`type`](#parameterType) is "array".** Describes the type of items in the array. collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are:
  • `csv` - comma separated values `foo,bar`.
  • `ssv` - space separated values `foo bar`.
  • `tsv` - tab separated values `foo\tbar`.
  • `pipes` - pipe separated values foo|bar.
  • `multi` - corresponds to multiple parameter instances instead of multiple values for a single instance `foo=bar&foo=baz`. This is valid only for parameters [`in`](#parameterIn) "query" or "formData".
Default value is `csv`. default | * | Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. (Note: "default" has no meaning for required parameters.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined [`type`](#parameterType) for this parameter. maximum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. exclusiveMaximum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. minimum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. exclusiveMinimum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. maxLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. minLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. pattern | `string` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. maxItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. minItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. uniqueItems | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. enum | [*] | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. multipleOf | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Parameter Object Examples ###### Body Parameters A body parameter with a referenced schema definition (normally for a model definition): ```js { "name": "user", "in": "body", "description": "user to add to the system", "required": true, "schema": { "$ref": "#/definitions/User" } } ``` ```yaml name: user in: body description: user to add to the system required: true schema: $ref: '#/definitions/User' ``` A body parameter that is an array of string values: ```js { "name": "user", "in": "body", "description": "user to add to the system", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ``` ```yaml name: user in: body description: user to add to the system required: true schema: type: array items: type: string ``` ###### Other Parameters A header parameter with an array of 64 bit integer numbers: ```js { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "type": "array", "items": { "type": "integer", "format": "int64" }, "collectionFormat": "csv" } ``` ```yaml name: token in: header description: token to be passed as a header required: true type: array items: type: integer format: int64 collectionFormat: csv ``` A path parameter of a string value: ```js { "name": "username", "in": "path", "description": "username to fetch", "required": true, "type": "string" } ``` ```yaml name: username in: path description: username to fetch required: true type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```js { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" } ``` ```yaml name: id in: query description: ID of the object to fetch required: false type: array items: type: string collectionFormat: multi ``` A form data with file type for a file upload: ```js { "name": "avatar", "in": "formData", "description": "The avatar of the user", "required": true, "type": "file" } ``` ```yaml name: avatar in: formData description: The avatar of the user required: true type: file ``` #### Items Object A limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located [`in`](#parameterIn) `"body"`. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- type | `string` | **Required.** The internal type of the array. The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, or `"array"`. Files and models are not allowed. format | `string` | The extending format for the previously mentioned [`type`](#parameterType). See [Data Type Formats](#dataTypeFormat) for further details. items | [Items Object](#itemsObject) | **Required if [`type`](#itemsType) is "array".** Describes the type of items in the array. collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are:
  • `csv` - comma separated values `foo,bar`.
  • `ssv` - space separated values `foo bar`.
  • `tsv` - tab separated values `foo\tbar`.
  • `pipes` - pipe separated values foo|bar.
Default value is `csv`. default | * | Declares the value of the item that the server will use if none is provided. (Note: "default" has no meaning for required items.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined [`type`](#itemsType) for the data type. maximum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. exclusiveMaximum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. minimum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. exclusiveMinimum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. maxLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. minLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. pattern | `string` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. maxItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. minItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. uniqueItems | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. enum | [*] | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. multipleOf | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Items Object Examples Items must be of type string and have the minimum length of 2 characters: ```js { "type": "string", "minLength": 2 } ``` ```yaml type: string minLength: 2 ``` An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive): ```js { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 63 } } ``` ```yaml type: array items: type: integer minimum: 0 maximum: 63 ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. It is not expected from the documentation to necessarily cover all possible HTTP response codes, since they may not be known in advance. However, it is expected from the documentation to cover a successful operation response and any known errors. The `default` can be used as the default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. It can be used to cover undeclared responses. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [Swagger Object's responses](#swaggerResponses) section. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {[HTTP Status Code](#httpCodes)} | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [Swagger Object's responses](#swaggerResponses) section. ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Responses Object Example A 200 response for successful operation and a default response for others (implying an error): ```js { "200": { "description": "a pet to be returned", "schema": { "$ref": "#/definitions/Pet" } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/ErrorModel" } } } ``` ```yaml '200': description: a pet to be returned schema: $ref: '#/definitions/Pet' default: description: Unexpected error schema: $ref: '#/definitions/ErrorModel' ``` #### Response Object Describes a single response from an API Operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **Required.** A short description of the response. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. schema | [Schema Object](#schemaObject) | A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the [Schema Object](#schemaObject), its root `type` value may also be `"file"`. This SHOULD be accompanied by a relevant `produces` mime-type. headers | [Headers Object](#headersObject) | A list of headers that are sent with the response. examples | [Example Object](#exampleObject) | An example of the response message. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Response Object Examples Response of an array of a complex type: ```js { "description": "A complex object array response", "schema": { "type": "array", "items": { "$ref": "#/definitions/VeryComplexType" } } } ``` ```yaml description: A complex object array response schema: type: array items: $ref: '#/definitions/VeryComplexType' ``` Response with a string type: ```js { "description": "A simple string response", "schema": { "type": "string" } } ``` ```yaml description: A simple string response schema: type: string ``` Response with headers: ```js { "description": "A simple string response", "schema": { "type": "string" }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "type": "integer" }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "type": "integer" }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "type": "integer" } } } ``` ```yaml description: A simple string response schema: type: string headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period type: integer ``` Response with no return value: ```js { "description": "object created" } ``` ```yaml description: object created ``` #### Headers Object Lists the headers that can be sent as part of a response. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [Header Object](#headerObject) | The name of the property corresponds to the name of the header. The value describes the type of the header. ##### Headers Object Example Rate-limit headers: ```js { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "type": "integer" }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "type": "integer" }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "type": "integer" } } ``` ```yaml X-Rate-Limit-Limit: description: The number of allowed requests in the current period type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period type: integer ``` #### Example Object Allows sharing examples for operation responses. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {[mime type](#mimeTypes)} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. ##### Example Object Example Example response for application/json mimetype of a Pet data type: ```js { "application/json": { "name": "Puma", "type": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" } } ``` ```yaml application/json: name: Puma type: Dog color: Black gender: Female breed: Mixed ``` #### Header Object Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the header. type | `string` | **Required.** The type of the object. The value MUST be one of `"string"`, `"number"`, `"integer"`, `"boolean"`, or `"array"`. format | `string` | The extending format for the previously mentioned [`type`](#stType). See [Data Type Formats](#dataTypeFormat) for further details. items | [Items Object](#itemsObject) | **Required if [`type`](#stType) is "array".** Describes the type of items in the array. collectionFormat | `string` | Determines the format of the array if type array is used. Possible values are:
  • `csv` - comma separated values `foo,bar`.
  • `ssv` - space separated values `foo bar`.
  • `tsv` - tab separated values `foo\tbar`.
  • `pipes` - pipe separated values foo|bar.
Default value is `csv`. default | * | Declares the value of the header that the server will use if none is provided. (Note: "default" has no meaning for required headers.) See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2. Unlike JSON Schema this value MUST conform to the defined [`type`](#headerDefault) for the header. maximum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. exclusiveMaximum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2. minimum | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. exclusiveMinimum | `boolean` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3. maxLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1. minLength | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2. pattern | `string` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3. maxItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2. minItems | `integer` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3. uniqueItems | `boolean` | https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4. enum | [*] | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1. multipleOf | `number` | See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Header Object Example A simple header with of an integer type: ```js { "description": "The number of allowed requests in the current period", "type": "integer" } ``` ```yaml description: The number of allowed requests in the current period type: integer ``` #### Tag Object Allows adding meta data to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag used there. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The name of the tag. description | `string` | A short description for the tag. [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Tag Object Example ```js { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Reference Object A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse. The Reference Object is a [JSON Reference](http://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value. For this specification, only [canonical dereferencing](https://tools.ietf.org/html/draft-zyp-json-schema-04#section-7.2.3) is supported. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **Required.** The reference string. ##### Reference Object Example ```js { "$ref": "#/definitions/Pet" } ``` ```yaml $ref: '#/definitions/Pet' ``` ##### Relative Schema File Example ```js { "$ref": "Pet.json" } ``` ```yaml $ref: 'Pet.yaml' ``` ##### Relative Files With Embedded Schema Example ```js { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: 'definitions.yaml#/Pet' ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is based on the [JSON Schema Specification Draft 4](http://json-schema.org/) and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation. Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-zyp-json-schema-04) and [JSON Schema Validation](https://tools.ietf.org/html/draft-fge-json-schema-validation-00). Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. The following properties are taken directly from the JSON Schema definition and follow the same specifications: - $ref - As a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) - format (See [Data Type Formats](#dataTypeFormat) for further details) - title - description ([GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) can be used for rich text representation) - default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object) - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum - maxLength - minLength - pattern - maxItems - minItems - uniqueItems - maxProperties - minProperties - required - enum - type The following properties are taken from the JSON Schema definition but their definitions were adjusted to the Swagger Specification. Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the [Schema Object](#schemaObject) definition is used instead. - items - allOf - properties - additionalProperties Other than the JSON Schema subset fields, the following fields may be used for further schema documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. 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 MUST NOT be sent as part of the request. Properties marked as `readOnly` being `true` SHOULD NOT be in the `required` list of the defined schema. Default value is `false`. 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 format of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ###### Composition and Inheritance (Polymorphism) Swagger allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes in an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, Swagger adds the support of the `discriminator` field. When used, the `discriminator` will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the `discriminator` field MUST be a required field. The value of the chosen property has to be the friendly name given to the model under the `definitions` property. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ##### Schema Object Examples ###### Primitive Sample Unlike previous versions of Swagger, Schema definitions can be used to describe primitive and arrays as well. ```js { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```js { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/definitions/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/definitions/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```js { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```js { "type": "object", "additionalProperties": { "$ref": "#/definitions/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/definitions/ComplexModel' ``` ###### Model with Example ```js { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```js { "definitions": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/definitions/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } ``` ```yaml definitions: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/definitions/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```js { "definitions": { "Pet": { "type": "object", "discriminator": "petType", "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat", "allOf": [ { "$ref": "#/definitions/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog", "allOf": [ { "$ref": "#/definitions/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } ``` ```yaml definitions: Pet: type: object discriminator: petType properties: name: type: string petType: type: string required: - name - petType Cat: description: A representation of a cat allOf: - $ref: '#/definitions/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting default: lazy enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: description: A representation of a dog allOf: - $ref: '#/definitions/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property should be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within the Items Object (`items`), it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URL of the namespace definition. Value SHOULD be in the form of a URL. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```js { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```js { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```js { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```js { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "http://swagger.io/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: http://swagger.io/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```js { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```js { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if no name is explicitly defined, the same name will be used both internally and externally: ```js { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the above example, the following definition can be used: ```js { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```js { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```js { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Definitions Object An object to hold data types that can be consumed and produced by operations. These data types can be primitives, arrays or models. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [Schema Object](#schemaObject) | A single definition, mapping a "name" to the schema it defines. ##### Definitions Object Example ```js { "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } } ``` ```yaml Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string ``` #### Parameters Definitions Object An object to hold parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here. This does *not* define global operation parameters. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [Parameter Object](#parameterObject) | A single parameter definition, mapping a "name" to the parameter it defines. ##### Parameters Definition Object Example ```js { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "type": "integer", "format": "int32" }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "type": "integer", "format": "int32" } } ``` ```yaml skipParam: name: skip in: query description: number of items to skip required: true type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true type: integer format: int32 ``` #### Responses Definitions Object An object to hold responses to be reused across operations. Response definitions can be referenced to the ones defined here. This does *not* define global operation responses. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [Response Object](#responseObject) | A single response definition, mapping a "name" to the response it defines. ##### Responses Definitions Object Example ```js { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "schema": { "$ref": "#/definitions/GeneralError" } } } ``` ```yaml NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error schema: $ref: '#/definitions/GeneralError' ``` #### Security Definitions Object A declaration of the security schemes available to be used in the specification. This does not enforce the security schemes on the operations and only serves to provide the relevant details for each scheme. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [Security Scheme Object](#securitySchemeObject) | A single security scheme definition, mapping a "name" to the scheme it defines. ##### Security Definitions Object Example ```js { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "authorizationUrl": "http://swagger.io/api/oauth/dialog", "flow": "implicit", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } ``` ```yaml api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 authorizationUrl: http://swagger.io/api/oauth/dialog flow: implicit scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Scheme Object Allows the definition of a security scheme that can be used by the operations. Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code). ##### Fixed Fields Field Name | Type | Validity | Description ---|:---:|---|--- type | `string` | Any | **Required.** The type of the security scheme. Valid values are `"basic"`, `"apiKey"` or `"oauth2"`. description | `string` | Any | A short description for security scheme. name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used. in | `string` | `apiKey` | **Required** The location of the API key. Valid values are `"query"` or `"header"`. flow | `string` | `oauth2` | **Required.** The flow used by the OAuth2 security scheme. Valid values are `"implicit"`, `"password"`, `"application"` or `"accessCode"`. authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"application"`, `"accessCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. ##### Patterned Fields Field Name | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Security Scheme Object Example ###### Basic Authentication Sample ```js { "type": "basic" } ``` ```yaml type: basic ``` ###### API Key Sample ```js { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### Implicit OAuth2 Sample ```js { "type": "oauth2", "authorizationUrl": "http://swagger.io/api/oauth/dialog", "flow": "implicit", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } ``` ```yaml type: oauth2 authorizationUrl: http://swagger.io/api/oauth/dialog flow: implicit scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Scopes Object Lists the available scopes for an OAuth2 security scheme. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | `string` | Maps between a name of a scope to a short description of it (as the value of the property). ##### Patterned Objects Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Swagger 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. See [Vendor Extensions](#vendorExtensions) for further details. ##### Scopes Object Example ```js { "write:pets": "modify pets in your account", "read:pets": "read your pets" } ``` ```yaml write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes). The name used for each property MUST correspond to a security scheme declared in the [Security Definitions](#securityDefinitionsObject). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name must correspond to a security scheme which is declared in the [Security Definitions](#securityDefinitions). If the security scheme is of type `"oauth2"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```js { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```js { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the Swagger Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are always prefixed by `"x-"` and can have any valid JSON format value. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the Swagger specification may be declared and remain empty, or completely be removed, even though they are inherently the core of the API documentation. The reasoning behind it is to allow an additional layer of access control over the documentation itself. While not part of the specification itself, certain libraries may choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples for this: 1. The [Paths Object](#pathsObject) may be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) may be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject) so the user will not be aware of its existence. This allows the documentation provider a finer control over what the viewer can see. OpenAPI-Specification-3.1.0/versions/3.0.0.md000066400000000000000000003630461401301652500203650ustar00rootroot00000000000000# OpenAPI Specification #### Version 3.0.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - [Relative References In URLs](#relativeReferences) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) ## Definitions ##### OpenAPI Document A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. ##### Media Types Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838](http://tools.ietf.org/html/rfc6838). Some examples of possible media type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](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). ## Specification ### Versions The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.) ### Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: ```json { "field": [ 1, 2, 3 ] } ``` All field names in the specification are **case sensitive**. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits long | `integer` | `int64` | signed 64 bits float | `number` | `float` | | double | `number` | `double` | | string | `string` | | | byte | `string` | `byte` | base64 encoded characters binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | date | `string` | `date` | As defined by `full-date` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) password | `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](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. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Info Object The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the application. description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example: ```json { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", "termsOfService": "http://example.com/terms/", "contact": { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Sample Pet Store App description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: support@example.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example: ```json { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support url: http://www.example.com/support email: support@example.com ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. url | `string` | A URL to the license used for the API. MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example: ```json { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } ``` ```yaml name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html ``` #### Server Object An object representing a Server. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", "description": "Development server" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): ```json { "servers": [ { "url": "https://development.gigantic-server.com/v1", "description": "Development server" }, { "url": "https://staging.gigantic-server.com/v1", "description": "Staging server" }, { "url": "https://api.gigantic-server.com/v1", "description": "Production server" } ] } ``` ```yaml servers: - url: https://development.gigantic-server.com/v1 description: Development server - url: https://staging.gigantic-server.com/v1 description: Staging server - url: https://api.gigantic-server.com/v1 description: Production server ``` The following shows how variables can be used for a server configuration: ```json { "servers": [ { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", "variables": { "username": { "default": "demo", "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" }, "port": { "enum": [ "8443", "443" ], "default": "8443" }, "basePath": { "default": "v2" } } } ] } ``` ```yaml servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server variables: username: # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - '8443' - '443' default: '8443' basePath: # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` #### Server Variable Object An object representing a Server Variable for server URL template substitution. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. default | `string` | **REQUIRED**. The default value to use for substitution, and to send, if an alternate value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer. description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Components Object Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. ##### Fixed Fields Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```json "components": { "schemas": { "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } }, "parameters": { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "schema": { "type": "integer", "format": "int32" } }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "schema" : { "type": "integer", "format": "int32" } } }, "responses": { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "http://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } } } ``` ```yaml components: schemas: Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string parameters: skipParam: name: skip in: query description: number of items to skip required: true schema: type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true schema: type: integer format: int32 responses: NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' securitySchemes: api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Paths Object Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Templating Matching Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: ``` /pets/{petId} /pets/mine ``` The following paths are considered identical and invalid: ``` /pets/{petId} /pets/{name} ``` The following may lead to ambiguous resolution: ``` /{entity}/me /books/{id} ``` ##### Paths Object Example ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to responses: '200': description: A list of pets. content: application/json: schema: type: array items: $ref: '#/components/schemas/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. summary| `string` | An optional, string summary, intended to apply to all operations in this path. description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Item Object Example ```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "responses": { "200": { "description": "pet response", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "error payload", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "simple" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById responses: '200': description: pet response content: '*/*' : schema: type: array items: $ref: '#/components/schemas/Pet' default: description: error payload content: 'text/html': schema: $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true schema: type: array style: simple items: type: string ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers. responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example ```json { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "operationId": "updatePetWithForm", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "description": "Updated name of the pet", "type": "string" }, "status": { "description": "Updated status of the pet", "type": "string" } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Pet updated.", "content": { "application/json": {}, "application/xml": {} } }, "405": { "description": "Invalid input", "content": { "application/json": {}, "application/xml": {} } } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: string requestBody: content: 'application/x-www-form-urlencoded': schema: properties: name: description: Updated name of the pet type: string status: description: Updated status of the pet type: string required: - status responses: '200': description: Pet updated. content: 'application/json': {} 'application/xml': {} '405': description: Invalid input content: 'application/json': {} 'application/xml': {} security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example ```json { "description": "Find more info here", "url": "https://example.com" } ``` ```yaml description: Find more info here url: https://example.com ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie". 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. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. 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. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- 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`. 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`. 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`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. 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. 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. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- 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. ##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `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. simple | `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. spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. ##### Style Examples Assume a parameter named `color` has one of the following values: ``` string -> "blue" array -> ["blue","black","brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` The following table shows examples of rendering differences for each value. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: ```json { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "style": "simple" } ``` ```yaml name: token in: header description: token to be passed as a header required: true schema: type: array items: type: integer format: int64 style: simple ``` A path parameter of a string value: ```json { "name": "username", "in": "path", "description": "username to fetch", "required": true, "schema": { "type": "string" } } ``` ```yaml name: username in: path description: username to fetch required: true schema: type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```json { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ``` ```yaml name: id in: query description: ID of the object to fetch required: false schema: type: array items: type: string style: form explode: true ``` A free-form query parameter, allowing undefined parameters of a specific type: ```json { "in": "query", "name": "freeForm", "schema": { "type": "object", "additionalProperties": { "type": "integer" }, }, "style": "form" } ``` ```yaml in: query name: freeForm schema: type: object additionalProperties: type: integer style: form ``` A complex parameter using `content` to define serialization: ```json { "in": "query", "name": "coordinates", "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "long" ], "properties": { "lat": { "type": "number" }, "long": { "type": "number" } } } } } } ``` ```yaml in: query name: coordinates content: application/json: schema: type: object required: - lat - long properties: lat: type: number long: type: number ``` #### Request Body Object Describes a single request body. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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/* required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Request Body Examples A request body with a referenced model definition. ```json { "description": "user to add to the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User Example", "externalValue": "http://foo.bar/examples/user-example.json" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User example in XML", "externalValue": "http://foo.bar/examples/user-example.xml" } } }, "text/plain": { "examples": { "user" : { "summary": "User example in Plain text", "externalValue": "http://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { "summary": "User example in other format", "externalValue": "http://foo.bar/examples/user-example.whatever" } } } } } ``` ```yaml description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example externalValue: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML externalValue: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in text plain format externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format externalValue: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: ```json { "description": "user to add to the system", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } ``` ```yaml description: user to add to the system required: true content: text/plain: schema: type: array items: type: string ``` #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. 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. 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. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Media Type Examples ```js { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", "value": { "name": "Fluffy", "petType": "Cat", "color": "White", "gender": "male", "breed": "Persian" } }, "dog": { "summary": "An example of a dog with a cat's name", "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" }, "frog": { "$ref": "#/components/examples/frog-example" } } } } } ``` ```yaml application/json: schema: $ref: "#/components/schemas/Pet" examples: cat: summary: An example of a cat value: name: Fluffy petType: Cat color: White gender: male breed: Persian dog: summary: An example of a dog with a cat's name value: name: Puma petType: Dog color: Black gender: Female breed: Mixed frog: $ref: "#/components/examples/frog-example" ``` ##### Considerations for File Uploads In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically: ```yaml # content transferred with base64 encoding schema: type: string format: base64 ``` ```yaml # content transferred in binary (octet-stream): schema: type: string format: binary ``` These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: ```yaml requestBody: content: application/octet-stream: # any media type is accepted, functionally equivalent to `*/*` schema: # a binary file of any type type: string format: binary ``` In addition, specific media types MAY be specified: ```yaml # multiple, specific media types may be specified: requestBody: content: # a binary file of type png or jpeg 'image/jpeg': schema: type: string format: binary 'image/png': schema: type: string format: binary ``` To upload multiple files, a `multipart` media type MUST be used: ```yaml requestBody: content: multipart/form-data: schema: properties: # The property name 'file' will be used for all files. file: type: array items: type: string format: binary ``` ##### Support for x-www-form-urlencoded Request Bodies To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following definition may be used: ```yaml requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: id: type: string format: uuid address: # complex types are stringified to support RFC 1866 type: object properties: {} ``` In 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. When 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`. ##### Special Considerations for `multipart` Content It 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. When 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`: * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` * If the property is complex, or an array of complex values, the default Content-Type is `application/json` * 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` Examples: ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: type: string format: uuid address: # default Content-Type for objects is `application/json` type: object properties: {} profileImage: # default Content-Type for string/binary is `application/octet-stream` type: string format: binary children: # default Content-Type for arrays is based on the `inner` type (text/plain here) type: array items: type: string addresses: # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) type: array items: type: '#/components/schemas/Address' ``` An `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. #### Encoding Object A single encoding definition applied to a single schema property. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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`. 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`. 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`. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example ```yaml requestBody: content: multipart/mixed: schema: type: object properties: id: # default is text/plain type: string format: uuid address: # default is application/json type: object properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object properties: {} profileImage: # default is application/octet-stream, need to declare an image type only! type: string format: binary encoding: historyMetadata: # require XML Content-Type in utf-8 encoding contentType: application/xml; charset=utf-8 profileImage: # only accept png/jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- [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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Responses Object Example A 200 response for a successful operation and a default response for others (implying an error): ```json { "200": { "description": "a pet to be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } ``` ```yaml '200': description: a pet to be returned content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorModel' ``` #### Response Object Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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/* 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). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples Response of an array of a complex type: ```json { "description": "A complex object array response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VeryComplexType" } } } } } ``` ```yaml description: A complex object array response content: application/json: schema: type: array items: $ref: '#/components/schemas/VeryComplexType' ``` Response with a string type: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } } } ``` ```yaml description: A simple string response representations: text/plain: schema: type: string ``` Plain text response with headers: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "schema": { "type": "integer" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer ``` Response with no return value: ```json { "description": "object created" } ``` ```yaml description: object created ``` #### Callback Object A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Key Expression The 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. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: ```http POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { "failedUrl" : "http://clientdomain.com/failed", "successUrls" : [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" ] } 201 Created Location: http://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- $url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent $request.query.queryUrl | http://clientdomain.com/stillrunning $request.header.content-Type | application/json $request.body#/failedUrl | http://clientdomain.com/stillrunning $request.body#/successUrls/2 | http://clientdomain.com/medium $response.header.Location | http://example.org/subscription/1 ##### Callback Object Example The following example shows a callback to the URL specified by the `id` and `email` property in the request body. ```yaml myWebhook: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: webhook successfully processed and no retries will be performed ``` #### Example Object ##### Fixed Fields Field Name | Type | Description ---|:---:|--- summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Example ```yaml # in a model schemas: properties: name: type: string examples: name: $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example # in a request body: requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: summary: This is an example in XML externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example externalValue: 'http://foo.bar/examples/address-example.txt' # in a parameter parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' examples: zip-example: $ref: '#/components/examples/zip-example' # in a response responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' examples: confirmation-success: $ref: '#/components/examples/confirmation-success' ``` #### Link Object The `Link object` represents a possible design-time link for a response. The 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. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For 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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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. 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). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. ```yaml paths: /users/{id}: parameters: - name: id in: path required: true description: the user identifier, as userId schema: type: string get: responses: '200': description: the user being returned content: application/json: schema: type: object properties: uuid: # the unique user id type: string format: uuid links: address: # the target link operationId operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` userId: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: - name: userid in: path required: true description: the user identifier, as userId schema: type: string # linked operation get: operationId: getUserAddress responses: '200': description: the user's address ``` When a runtime expression fails to evaluate, no parameter value is passed to the target operation. Values from the response body can be used to drive a linked operation. ```yaml links: address: operationId: getUserAddressByUUID parameters: # get the `id` field from the request path parameter named `id` userUuid: $response.body#/uuid ``` Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` or an absolute `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. ##### Runtime Expressions Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ``` expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) source = ( header-reference | query-reference | path-reference | body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" fragment] fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) name = *( char ) char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) ``` The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: ##### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request 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. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). ##### Header Object Example A simple header of type `integer`: ```json { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } } ``` ```yaml description: The number of allowed requests in the current period schema: type: integer ``` #### Tag Object Adds metadata to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example ```json { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Examples Object In an `example`, a JSON Reference MAY be used, with the explicit restriction that examples having a JSON format with object named `$ref` are not allowed. Therefore, that `example`, structurally, can be either a string primitive or an object, similar to `additionalProperties`. In all cases, the payload is expected to be compatible with the type schema for the associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if they are incompatible. ```yaml # in a model schemas: properties: name: type: string example: $ref: http://foo.bar#/examples/name-example # in a request body, note the plural `examples` requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: value: {"foo": "bar"} bar: value: {"bar": "baz"} 'application/xml': examples: xml: externalValue: 'http://foo.bar/examples/address-example.xml' 'text/plain': examples: text: externalValue: 'http://foo.bar/examples/address-example.txt' # in a parameter parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' example: $ref: 'http://foo.bar#/examples/zip-example' # in a response, note the singular `example`: responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' example: $ref: http://foo.bar#/examples/address-example.json ``` #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. The 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. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. ##### Reference Object Example ```json { "$ref": "#/components/schemas/Pet" } ``` ```yaml $ref: '#/components/schemas/Pet' ``` ##### Relative Schema Document Example ```json { "$ref": "Pet.json" } ``` ```yaml $ref: Pet.yaml ``` ##### Relative Documents With Embedded Schema Example ```json { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: definitions.yaml#/Pet ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/). For 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). Unless stated otherwise, the property definitions follow the JSON Schema. ##### Properties The following properties are taken directly from the JSON Schema definition and follow the same specifications: - title - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum - maxLength - minLength - 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) - maxItems - minItems - uniqueItems - maxProperties - minProperties - required - enum The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. - type - Value MUST be a string. Multiple types via an array are not supported. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - 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`. - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. - 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. - 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`. Alternatively, 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. Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. 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. readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ##### Schema Object Examples ###### Primitive Sample ```json { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/components/schemas/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```json { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```json { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/components/schemas/ComplexModel' ``` ###### Model with Example ```json { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```json { "components": { "schemas": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/components/schemas/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } } ``` ```yaml components: schemas: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```json { "components": { "schemas": { "Pet": { "type": "object", "discriminator": { "propertyName": "petType" }, "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } } ``` ```yaml components: schemas: Pet: type: object discriminator: propertyName: petType properties: name: type: string petType: type: string required: - name - petType Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. The discriminator attribute is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' ``` which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: pet_type ``` The 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: ``` { "id": 12345, "pet_type": "Cat" } ``` Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: pet_type mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. For example: ``` components: schemas: Pet: type: object required: - pet_type properties: pet_type: type: string discriminator: propertyName: pet_type mapping: cachorro: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean ``` a payload like this: ``` { "pet_type": "Cat", "name": "misty" } ``` will indicate that the `Cat` schema be used. Likewise this schema: ``` { "pet_type": "cachorro", "bark": "soft" } ``` will map to `Dog` because of the definition in the `mappings` element. #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```json { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```json { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```json { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "http://example.com/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: http://example.com/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the naming problem in the example above, the following definition can be used: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example ###### Basic Authentication Sample ```json { "type": "http", "scheme": "basic" } ``` ```yaml type: http scheme: basic ``` ###### API Key Sample ```json { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### JWT Bearer Sample ```json { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", } ``` ```yaml type: http scheme: bearer bearerFormat: JWT ``` ###### Implicit OAuth2 Sample ```json { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### OAuth Flows Object Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### OAuth Flow Object Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples ```JSON { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```YAML type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the [Open API object](#oasObject) or [Operation Object](#operationObject), only one of Security Requirement Objects in the list needs to be satisfied to authorize the request. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```json { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```json { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples of this: 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification OpenAPI-Specification-3.1.0/versions/3.0.1.md000066400000000000000000003575431401301652500203730ustar00rootroot00000000000000# OpenAPI Specification #### Version 3.0.1 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - [Relative References In URLs](#relativeReferences) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) ## Definitions ##### OpenAPI Document A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. ##### Media Types Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838). Some examples of possible media type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification ### Versions The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.) ### Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: ```json { "field": [ 1, 2, 3 ] } ``` All field names in the specification are **case sensitive**. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits long | `integer` | `int64` | signed 64 bits float | `number` | `float` | | double | `number` | `double` | | string | `string` | | | byte | `string` | `byte` | base64 encoded characters binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | date | `string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) password | `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Info Object The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the application. description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example: ```json { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", "termsOfService": "http://example.com/terms/", "contact": { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Sample Pet Store App description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: support@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example: ```json { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support url: http://www.example.com/support email: support@example.com ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. url | `string` | A URL to the license used for the API. MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example: ```json { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } ``` ```yaml name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html ``` #### Server Object An object representing a Server. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", "description": "Development server" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): ```json { "servers": [ { "url": "https://development.gigantic-server.com/v1", "description": "Development server" }, { "url": "https://staging.gigantic-server.com/v1", "description": "Staging server" }, { "url": "https://api.gigantic-server.com/v1", "description": "Production server" } ] } ``` ```yaml servers: - url: https://development.gigantic-server.com/v1 description: Development server - url: https://staging.gigantic-server.com/v1 description: Staging server - url: https://api.gigantic-server.com/v1 description: Production server ``` The following shows how variables can be used for a server configuration: ```json { "servers": [ { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", "variables": { "username": { "default": "demo", "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" }, "port": { "enum": [ "8443", "443" ], "default": "8443" }, "basePath": { "default": "v2" } } } ] } ``` ```yaml servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server variables: username: # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - '8443' - '443' default: '8443' basePath: # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` #### Server Variable Object An object representing a Server Variable for server URL template substitution. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. default | `string` | **REQUIRED**. The default value to use for substitution, and to send, if an alternate value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer. description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Components Object Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. ##### Fixed Fields Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```json "components": { "schemas": { "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } }, "parameters": { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "schema": { "type": "integer", "format": "int32" } }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "schema" : { "type": "integer", "format": "int32" } } }, "responses": { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "http://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } } } ``` ```yaml components: schemas: Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string parameters: skipParam: name: skip in: query description: number of items to skip required: true schema: type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true schema: type: integer format: int32 responses: NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' securitySchemes: api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Paths Object Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Templating Matching Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: ``` /pets/{petId} /pets/mine ``` The following paths are considered identical and invalid: ``` /pets/{petId} /pets/{name} ``` The following may lead to ambiguous resolution: ``` /{entity}/me /books/{id} ``` ##### Paths Object Example ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to responses: '200': description: A list of pets. content: application/json: schema: type: array items: $ref: '#/components/schemas/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. summary| `string` | An optional, string summary, intended to apply to all operations in this path. description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Item Object Example ```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "responses": { "200": { "description": "pet response", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "error payload", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "simple" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById responses: '200': description: pet response content: '*/*' : schema: type: array items: $ref: '#/components/schemas/Pet' default: description: error payload content: 'text/html': schema: $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true schema: type: array style: simple items: type: string ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers. responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example ```json { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "operationId": "updatePetWithForm", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "description": "Updated name of the pet", "type": "string" }, "status": { "description": "Updated status of the pet", "type": "string" } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Pet updated.", "content": { "application/json": {}, "application/xml": {} } }, "405": { "description": "Invalid input", "content": { "application/json": {}, "application/xml": {} } } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: string requestBody: content: 'application/x-www-form-urlencoded': schema: properties: name: description: Updated name of the pet type: string status: description: Updated status of the pet type: string required: - status responses: '200': description: Pet updated. content: 'application/json': {} 'application/xml': {} '405': description: Invalid input content: 'application/json': {} 'application/xml': {} security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example ```json { "description": "Find more info here", "url": "https://example.com" } ``` ```yaml description: Find more info here url: https://example.com ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie". 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. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. 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. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- 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`. 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`. 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`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. 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. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- 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. ##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `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. simple | `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. spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. ##### Style Examples Assume a parameter named `color` has one of the following values: ``` string -> "blue" array -> ["blue","black","brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` The following table shows examples of rendering differences for each value. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: ```json { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "style": "simple" } ``` ```yaml name: token in: header description: token to be passed as a header required: true schema: type: array items: type: integer format: int64 style: simple ``` A path parameter of a string value: ```json { "name": "username", "in": "path", "description": "username to fetch", "required": true, "schema": { "type": "string" } } ``` ```yaml name: username in: path description: username to fetch required: true schema: type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```json { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ``` ```yaml name: id in: query description: ID of the object to fetch required: false schema: type: array items: type: string style: form explode: true ``` A free-form query parameter, allowing undefined parameters of a specific type: ```json { "in": "query", "name": "freeForm", "schema": { "type": "object", "additionalProperties": { "type": "integer" }, }, "style": "form" } ``` ```yaml in: query name: freeForm schema: type: object additionalProperties: type: integer style: form ``` A complex parameter using `content` to define serialization: ```json { "in": "query", "name": "coordinates", "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "long" ], "properties": { "lat": { "type": "number" }, "long": { "type": "number" } } } } } } ``` ```yaml in: query name: coordinates content: application/json: schema: type: object required: - lat - long properties: lat: type: number long: type: number ``` #### Request Body Object Describes a single request body. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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/* required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Request Body Examples A request body with a referenced model definition. ```json { "description": "user to add to the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User Example", "externalValue": "http://foo.bar/examples/user-example.json" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User example in XML", "externalValue": "http://foo.bar/examples/user-example.xml" } } }, "text/plain": { "examples": { "user" : { "summary": "User example in Plain text", "externalValue": "http://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { "summary": "User example in other format", "externalValue": "http://foo.bar/examples/user-example.whatever" } } } } } ``` ```yaml description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example externalValue: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML externalValue: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in text plain format externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format externalValue: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: ```json { "description": "user to add to the system", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } ``` ```yaml description: user to add to the system required: true content: text/plain: schema: type: array items: type: string ``` #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Media Type Examples ```js { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", "value": { "name": "Fluffy", "petType": "Cat", "color": "White", "gender": "male", "breed": "Persian" } }, "dog": { "summary": "An example of a dog with a cat's name", "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" }, "frog": { "$ref": "#/components/examples/frog-example" } } } } } ``` ```yaml application/json: schema: $ref: "#/components/schemas/Pet" examples: cat: summary: An example of a cat value: name: Fluffy petType: Cat color: White gender: male breed: Persian dog: summary: An example of a dog with a cat's name value: name: Puma petType: Dog color: Black gender: Female breed: Mixed frog: $ref: "#/components/examples/frog-example" ``` ##### Considerations for File Uploads In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically: ```yaml # content transferred with base64 encoding schema: type: string format: base64 ``` ```yaml # content transferred in binary (octet-stream): schema: type: string format: binary ``` These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: ```yaml requestBody: content: application/octet-stream: # any media type is accepted, functionally equivalent to `*/*` schema: # a binary file of any type type: string format: binary ``` In addition, specific media types MAY be specified: ```yaml # multiple, specific media types may be specified: requestBody: content: # a binary file of type png or jpeg 'image/jpeg': schema: type: string format: binary 'image/png': schema: type: string format: binary ``` To upload multiple files, a `multipart` media type MUST be used: ```yaml requestBody: content: multipart/form-data: schema: properties: # The property name 'file' will be used for all files. file: type: array items: type: string format: binary ``` ##### Support for x-www-form-urlencoded Request Bodies To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following definition may be used: ```yaml requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: id: type: string format: uuid address: # complex types are stringified to support RFC 1866 type: object properties: {} ``` In 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. When 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`. ##### Special Considerations for `multipart` Content It 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. When 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`: * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` * If the property is complex, or an array of complex values, the default Content-Type is `application/json` * 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` Examples: ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: type: string format: uuid address: # default Content-Type for objects is `application/json` type: object properties: {} profileImage: # default Content-Type for string/binary is `application/octet-stream` type: string format: binary children: # default Content-Type for arrays is based on the `inner` type (text/plain here) type: array items: type: string addresses: # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) type: array items: type: '#/components/schemas/Address' ``` An `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. #### Encoding Object A single encoding definition applied to a single schema property. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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`. 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`. 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`. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example ```yaml requestBody: content: multipart/mixed: schema: type: object properties: id: # default is text/plain type: string format: uuid address: # default is application/json type: object properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object properties: {} profileImage: # default is application/octet-stream, need to declare an image type only! type: string format: binary encoding: historyMetadata: # require XML Content-Type in utf-8 encoding contentType: application/xml; charset=utf-8 profileImage: # only accept png/jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- [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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Responses Object Example A 200 response for a successful operation and a default response for others (implying an error): ```json { "200": { "description": "a pet to be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } ``` ```yaml '200': description: a pet to be returned content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorModel' ``` #### Response Object Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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/* 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). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples Response of an array of a complex type: ```json { "description": "A complex object array response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VeryComplexType" } } } } } ``` ```yaml description: A complex object array response content: application/json: schema: type: array items: $ref: '#/components/schemas/VeryComplexType' ``` Response with a string type: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string ``` Plain text response with headers: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "schema": { "type": "integer" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer ``` Response with no return value: ```json { "description": "object created" } ``` ```yaml description: object created ``` #### Callback Object A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Key Expression The 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. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: ```http POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { "failedUrl" : "http://clientdomain.com/failed", "successUrls" : [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" ] } 201 Created Location: http://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- $url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent $request.query.queryUrl | http://clientdomain.com/stillrunning $request.header.content-Type | application/json $request.body#/failedUrl | http://clientdomain.com/stillrunning $request.body#/successUrls/2 | http://clientdomain.com/medium $response.header.Location | http://example.org/subscription/1 ##### Callback Object Example The following example shows a callback to the URL specified by the `id` and `email` property in the request body. ```yaml myWebhook: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: webhook successfully processed and no retries will be performed ``` #### Example Object ##### Fixed Fields Field Name | Type | Description ---|:---:|--- summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Example ```yaml # in a model schemas: properties: name: type: string examples: name: $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example # in a request body: requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: summary: This is an example in XML externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example externalValue: 'http://foo.bar/examples/address-example.txt' # in a parameter parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' examples: zip-example: $ref: '#/components/examples/zip-example' # in a response responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' examples: confirmation-success: $ref: '#/components/examples/confirmation-success' ``` #### Link Object The `Link object` represents a possible design-time link for a response. The 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. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For 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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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. 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). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. ```yaml paths: /users/{id}: parameters: - name: id in: path required: true description: the user identifier, as userId schema: type: string get: responses: '200': description: the user being returned content: application/json: schema: type: object properties: uuid: # the unique user id type: string format: uuid links: address: # the target link operationId operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` userId: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: - name: userid in: path required: true description: the user identifier, as userId schema: type: string # linked operation get: operationId: getUserAddress responses: '200': description: the user's address ``` When a runtime expression fails to evaluate, no parameter value is passed to the target operation. Values from the response body can be used to drive a linked operation. ```yaml links: address: operationId: getUserAddressByUUID parameters: # get the `uuid` field from the `uuid` field in the response body userUuid: $response.body#/uuid ``` Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` or an absolute `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. ##### Runtime Expressions Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ``` expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) source = ( header-reference | query-reference | path-reference | body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" fragment] fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) name = *( char ) char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) ``` The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: ##### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request 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. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). ##### Header Object Example A simple header of type `integer`: ```json { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } } ``` ```yaml description: The number of allowed requests in the current period schema: type: integer ``` #### Tag Object Adds metadata to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example ```json { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. The 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. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. ##### Reference Object Example ```json { "$ref": "#/components/schemas/Pet" } ``` ```yaml $ref: '#/components/schemas/Pet' ``` ##### Relative Schema Document Example ```json { "$ref": "Pet.json" } ``` ```yaml $ref: Pet.yaml ``` ##### Relative Documents With Embedded Schema Example ```json { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: definitions.yaml#/Pet ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/). For 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). Unless stated otherwise, the property definitions follow the JSON Schema. ##### Properties The following properties are taken directly from the JSON Schema definition and follow the same specifications: - title - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum - maxLength - minLength - 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) - maxItems - minItems - uniqueItems - maxProperties - minProperties - required - enum The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. - type - Value MUST be a string. Multiple types via an array are not supported. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - 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`. - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. - 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. - 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`. Alternatively, 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. Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. 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. readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ##### Schema Object Examples ###### Primitive Sample ```json { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/components/schemas/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```json { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```json { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/components/schemas/ComplexModel' ``` ###### Model with Example ```json { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```json { "components": { "schemas": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/components/schemas/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } } ``` ```yaml components: schemas: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```json { "components": { "schemas": { "Pet": { "type": "object", "discriminator": { "propertyName": "petType" }, "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } } ``` ```yaml components: schemas: Pet: type: object discriminator: propertyName: petType properties: name: type: string petType: type: string required: - name - petType Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. The discriminator attribute is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' ``` which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: pet_type ``` The 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: ``` { "id": 12345, "pet_type": "Cat" } ``` Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ``` MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: pet_type mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. For example: ``` components: schemas: Pet: type: object required: - pet_type properties: pet_type: type: string discriminator: propertyName: pet_type mapping: cachorro: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean ``` a payload like this: ``` { "pet_type": "Cat", "name": "misty" } ``` will indicate that the `Cat` schema be used. Likewise this schema: ``` { "pet_type": "cachorro", "bark": "soft" } ``` will map to `Dog` because of the definition in the `mappings` element. #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```json { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```json { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```json { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "http://example.com/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: http://example.com/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the naming problem in the example above, the following definition can be used: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example ###### Basic Authentication Sample ```json { "type": "http", "scheme": "basic" } ``` ```yaml type: http scheme: basic ``` ###### API Key Sample ```json { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### JWT Bearer Sample ```json { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", } ``` ```yaml type: http scheme: bearer bearerFormat: JWT ``` ###### Implicit OAuth2 Sample ```json { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### OAuth Flows Object Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### OAuth Flow Object Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples ```JSON { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```YAML type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the [Open API object](#oasObject) or [Operation Object](#operationObject), only one of Security Requirement Objects in the list needs to be satisfied to authorize the request. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```json { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```json { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples of this: 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification OpenAPI-Specification-3.1.0/versions/3.0.2.md000066400000000000000000003611401401301652500203600ustar00rootroot00000000000000# OpenAPI Specification #### Version 3.0.2 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - [Relative References In URLs](#relativeReferences) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) ## Definitions ##### OpenAPI Document A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. ##### Media Types Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838). Some examples of possible media type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification ### Versions The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`. An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.) ### Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: ```json { "field": [ 1, 2, 3 ] } ``` All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments ------ | -------- | -------- `integer` | `int32` | signed 32 bits `integer` | `int64` | signed 64 bits (a.k.a long) `number` | `float` | | `number` | `double` | | `string` | | | `string` | `byte` | base64 encoded characters `string` | `binary` | any sequence of octets `boolean` | | | `string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) `string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](http://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Info Object The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the application. description | `string` | A short description of the application. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example ```json { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", "termsOfService": "http://example.com/terms/", "contact": { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Sample Pet Store App description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: support@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example ```json { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support url: http://www.example.com/support email: support@example.com ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. url | `string` | A URL to the license used for the API. MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example ```json { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } ``` ```yaml name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html ``` #### Server Object An object representing a Server. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", "description": "Development server" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): ```json { "servers": [ { "url": "https://development.gigantic-server.com/v1", "description": "Development server" }, { "url": "https://staging.gigantic-server.com/v1", "description": "Staging server" }, { "url": "https://api.gigantic-server.com/v1", "description": "Production server" } ] } ``` ```yaml servers: - url: https://development.gigantic-server.com/v1 description: Development server - url: https://staging.gigantic-server.com/v1 description: Staging server - url: https://api.gigantic-server.com/v1 description: Production server ``` The following shows how variables can be used for a server configuration: ```json { "servers": [ { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", "variables": { "username": { "default": "demo", "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" }, "port": { "enum": [ "8443", "443" ], "default": "8443" }, "basePath": { "default": "v2" } } } ] } ``` ```yaml servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server variables: username: # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - '8443' - '443' default: '8443' basePath: # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` #### Server Variable Object An object representing a Server Variable for server URL template substitution. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Components Object Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. ##### Fixed Fields Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```json "components": { "schemas": { "GeneralError": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } }, "parameters": { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "schema": { "type": "integer", "format": "int32" } }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "schema" : { "type": "integer", "format": "int32" } } }, "responses": { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "http://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } } } ``` ```yaml components: schemas: GeneralError: type: object properties: code: type: integer format: int32 message: type: string Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string parameters: skipParam: name: skip in: query description: number of items to skip required: true schema: type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true schema: type: integer format: int32 responses: NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' securitySchemes: api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Paths Object Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Templating Matching Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: ``` /pets/{petId} /pets/mine ``` The following paths are considered identical and invalid: ``` /pets/{petId} /pets/{name} ``` The following may lead to ambiguous resolution: ``` /{entity}/me /books/{id} ``` ##### Paths Object Example ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to responses: '200': description: A list of pets. content: application/json: schema: type: array items: $ref: '#/components/schemas/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*. summary| `string` | An optional, string summary, intended to apply to all operations in this path. description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Item Object Example ```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "responses": { "200": { "description": "pet response", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "error payload", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "simple" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById responses: '200': description: pet response content: '*/*' : schema: type: array items: $ref: '#/components/schemas/Pet' default: description: error payload content: 'text/html': schema: $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true schema: type: array style: simple items: type: string ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers. responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example ```json { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "operationId": "updatePetWithForm", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "description": "Updated name of the pet", "type": "string" }, "status": { "description": "Updated status of the pet", "type": "string" } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Pet updated.", "content": { "application/json": {}, "application/xml": {} } }, "405": { "description": "Method Not Allowed", "content": { "application/json": {}, "application/xml": {} } } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: string requestBody: content: 'application/x-www-form-urlencoded': schema: properties: name: description: Updated name of the pet type: string status: description: Updated status of the pet type: string required: - status responses: '200': description: Pet updated. content: 'application/json': {} 'application/xml': {} '405': description: Method Not Allowed content: 'application/json': {} 'application/xml': {} security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example ```json { "description": "Find more info here", "url": "https://example.com" } ``` ```yaml description: Find more info here url: https://example.com ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie". 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. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. 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. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- 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`. 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`. 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`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. example | Any | Example of the media type. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. 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. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- 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. ##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `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. simple | `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. spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. ##### Style Examples Assume a parameter named `color` has one of the following values: ``` string -> "blue" array -> ["blue","black","brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` The following table shows examples of rendering differences for each value. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | --------|------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: ```json { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "style": "simple" } ``` ```yaml name: token in: header description: token to be passed as a header required: true schema: type: array items: type: integer format: int64 style: simple ``` A path parameter of a string value: ```json { "name": "username", "in": "path", "description": "username to fetch", "required": true, "schema": { "type": "string" } } ``` ```yaml name: username in: path description: username to fetch required: true schema: type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```json { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ``` ```yaml name: id in: query description: ID of the object to fetch required: false schema: type: array items: type: string style: form explode: true ``` A free-form query parameter, allowing undefined parameters of a specific type: ```json { "in": "query", "name": "freeForm", "schema": { "type": "object", "additionalProperties": { "type": "integer" }, }, "style": "form" } ``` ```yaml in: query name: freeForm schema: type: object additionalProperties: type: integer style: form ``` A complex parameter using `content` to define serialization: ```json { "in": "query", "name": "coordinates", "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "long" ], "properties": { "lat": { "type": "number" }, "long": { "type": "number" } } } } } } ``` ```yaml in: query name: coordinates content: application/json: schema: type: object required: - lat - long properties: lat: type: number long: type: number ``` #### Request Body Object Describes a single request body. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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/* required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Request Body Examples A request body with a referenced model definition. ```json { "description": "user to add to the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User Example", "externalValue": "http://foo.bar/examples/user-example.json" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User example in XML", "externalValue": "http://foo.bar/examples/user-example.xml" } } }, "text/plain": { "examples": { "user" : { "summary": "User example in Plain text", "externalValue": "http://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { "summary": "User example in other format", "externalValue": "http://foo.bar/examples/user-example.whatever" } } } } } ``` ```yaml description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example externalValue: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML externalValue: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in text plain format externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format externalValue: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: ```json { "description": "user to add to the system", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } ``` ```yaml description: user to add to the system required: true content: text/plain: schema: type: array items: type: string ``` #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, or parameter. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Media Type Examples ```json { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", "value": { "name": "Fluffy", "petType": "Cat", "color": "White", "gender": "male", "breed": "Persian" } }, "dog": { "summary": "An example of a dog with a cat's name", "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" }, "frog": { "$ref": "#/components/examples/frog-example" } } } } } ``` ```yaml application/json: schema: $ref: "#/components/schemas/Pet" examples: cat: summary: An example of a cat value: name: Fluffy petType: Cat color: White gender: male breed: Persian dog: summary: An example of a dog with a cat's name value: name: Puma petType: Dog color: Black gender: Female breed: Mixed frog: $ref: "#/components/examples/frog-example" ``` ##### Considerations for File Uploads In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically: ```yaml # content transferred with base64 encoding schema: type: string format: base64 ``` ```yaml # content transferred in binary (octet-stream): schema: type: string format: binary ``` These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: ```yaml requestBody: content: application/octet-stream: # any media type is accepted, functionally equivalent to `*/*` schema: # a binary file of any type type: string format: binary ``` In addition, specific media types MAY be specified: ```yaml # multiple, specific media types may be specified: requestBody: content: # a binary file of type png or jpeg 'image/jpeg': schema: type: string format: binary 'image/png': schema: type: string format: binary ``` To upload multiple files, a `multipart` media type MUST be used: ```yaml requestBody: content: multipart/form-data: schema: properties: # The property name 'file' will be used for all files. file: type: array items: type: string format: binary ``` ##### Support for x-www-form-urlencoded Request Bodies To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following definition may be used: ```yaml requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: id: type: string format: uuid address: # complex types are stringified to support RFC 1866 type: object properties: {} ``` In 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. When 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`. ##### Special Considerations for `multipart` Content It 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. When 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`: * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` * If the property is complex, or an array of complex values, the default Content-Type is `application/json` * 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` Examples: ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: type: string format: uuid address: # default Content-Type for objects is `application/json` type: object properties: {} profileImage: # default Content-Type for string/binary is `application/octet-stream` type: string format: binary children: # default Content-Type for arrays is based on the `inner` type (text/plain here) type: array items: type: string addresses: # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) type: array items: type: '#/components/schemas/Address' ``` An `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. #### Encoding Object A single encoding definition applied to a single schema property. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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`. 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`. 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`. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example ```yaml requestBody: content: multipart/mixed: schema: type: object properties: id: # default is text/plain type: string format: uuid address: # default is application/json type: object properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object properties: {} profileImage: # default is application/octet-stream, need to declare an image type only! type: string format: binary encoding: historyMetadata: # require XML Content-Type in utf-8 encoding contentType: application/xml; charset=utf-8 profileImage: # only accept png/jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- [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]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Responses Object Example A 200 response for a successful operation and a default response for others (implying an error): ```json { "200": { "description": "a pet to be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } ``` ```yaml '200': description: a pet to be returned content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorModel' ``` #### Response Object Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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/* 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). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples Response of an array of a complex type: ```json { "description": "A complex object array response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VeryComplexType" } } } } } ``` ```yaml description: A complex object array response content: application/json: schema: type: array items: $ref: '#/components/schemas/VeryComplexType' ``` Response with a string type: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string ``` Plain text response with headers: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "schema": { "type": "integer" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer ``` Response with no return value: ```json { "description": "object created" } ``` ```yaml description: object created ``` #### Callback Object A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Key Expression The 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. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: ```http POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { "failedUrl" : "http://clientdomain.com/failed", "successUrls" : [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" ] } 201 Created Location: http://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- $url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent $request.query.queryUrl | http://clientdomain.com/stillrunning $request.header.content-Type | application/json $request.body#/failedUrl | http://clientdomain.com/failed $request.body#/successUrls/2 | http://clientdomain.com/medium $response.header.Location | http://example.org/subscription/1 ##### Callback Object Example The following example shows a callback to the URL specified by the `id` and `email` property in the request body. ```yaml myWebhook: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: webhook successfully processed and no retries will be performed ``` #### Example Object ##### Fixed Fields Field Name | Type | Description ---|:---:|--- summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. 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. 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Examples In a model: ```yaml schemas: properties: name: type: string examples: name: $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example ``` In a request body: ```yaml requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: summary: This is an example in XML externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example externalValue: 'http://foo.bar/examples/address-example.txt' ``` In a parameter: ```yaml parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' examples: zip-example: $ref: '#/components/examples/zip-example' ``` In a response: ```yaml responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' examples: confirmation-success: $ref: '#/components/examples/confirmation-success' ``` #### Link Object The `Link object` represents a possible design-time link for a response. The 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. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For 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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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. 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). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. ```yaml paths: /users/{id}: parameters: - name: id in: path required: true description: the user identifier, as userId schema: type: string get: responses: '200': description: the user being returned content: application/json: schema: type: object properties: uuid: # the unique user id type: string format: uuid links: address: # the target link operationId operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` userId: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: - name: userid in: path required: true description: the user identifier, as userId schema: type: string # linked operation get: operationId: getUserAddress responses: '200': description: the user's address ``` When a runtime expression fails to evaluate, no parameter value is passed to the target operation. Values from the response body can be used to drive a linked operation. ```yaml links: address: operationId: getUserAddressByUUID parameters: # get the `uuid` field from the `uuid` field in the response body userUuid: $response.body#/uuid ``` Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` or an absolute `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. ##### Runtime Expressions Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ``` expression = ( "$url" | "$method" | "$statusCode" | "$request." source | "$response." source ) source = ( header-reference | query-reference | path-reference | body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" fragment] fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) name = *( char ) char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7) token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6) ``` The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: ##### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request 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. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). ##### Header Object Example A simple header of type `integer`: ```json { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } } ``` ```yaml description: The number of allowed requests in the current period schema: type: integer ``` #### Tag Object Adds metadata to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example ```json { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. The 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. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. ##### Reference Object Example ```json { "$ref": "#/components/schemas/Pet" } ``` ```yaml $ref: '#/components/schemas/Pet' ``` ##### Relative Schema Document Example ```json { "$ref": "Pet.json" } ``` ```yaml $ref: Pet.yaml ``` ##### Relative Documents With Embedded Schema Example ```json { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: definitions.yaml#/Pet ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the [JSON Schema Specification Wright Draft 00](http://json-schema.org/). For 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). Unless stated otherwise, the property definitions follow the JSON Schema. ##### Properties The following properties are taken directly from the JSON Schema definition and follow the same specifications: - title - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum - maxLength - minLength - 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) - maxItems - minItems - uniqueItems - maxProperties - minProperties - required - enum The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. - type - Value MUST be a string. Multiple types via an array are not supported. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - 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`. - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`. - description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. - 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. - 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`. Alternatively, 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. Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. 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. readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ##### Schema Object Examples ###### Primitive Sample ```json { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/components/schemas/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```json { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```json { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/components/schemas/ComplexModel' ``` ###### Model with Example ```json { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```json { "components": { "schemas": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/components/schemas/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } } ``` ```yaml components: schemas: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```json { "components": { "schemas": { "Pet": { "type": "object", "discriminator": { "propertyName": "petType" }, "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } } ``` ```yaml components: schemas: Pet: type: object discriminator: propertyName: petType properties: name: type: string petType: type: string required: - name - petType Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' ``` which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: petType ``` The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: ```json { "id": 12345, "petType": "Cat" } ``` Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. For example: ```yaml components: schemas: Pet: type: object required: - petType properties: petType: type: string discriminator: propertyName: petType mapping: dog: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean ``` a payload like this: ```json { "petType": "Cat", "name": "misty" } ``` will indicate that the `Cat` schema be used. Likewise this schema: ```json { "petType": "dog", "bark": "soft" } ``` will map to `Dog` because of the definition in the `mappings` element. #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```json { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```json { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```json { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "http://example.com/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: http://example.com/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the naming problem in the example above, the following definition can be used: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example ###### Basic Authentication Sample ```json { "type": "http", "scheme": "basic" } ``` ```yaml type: http scheme: basic ``` ###### API Key Sample ```json { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### JWT Bearer Sample ```json { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", } ``` ```yaml type: http scheme: bearer bearerFormat: JWT ``` ###### Implicit OAuth2 Sample ```json { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### OAuth Flows Object Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### OAuth Flow Object Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples ```JSON { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```json { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```json { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples of this: 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification OpenAPI-Specification-3.1.0/versions/3.0.3.md000066400000000000000000003664441401301652500203750ustar00rootroot00000000000000# OpenAPI Specification #### Version 3.0.3 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - [Relative References In URLs](#relativeReferences) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) ## Definitions ##### OpenAPI Document A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). ##### Media Types Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838). Some examples of possible media type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification ### Versions The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification. The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example. Each new minor version of the OpenAPI Specification SHALL allow any OpenAPI document that is valid against any previous minor version of the Specification, within the same major version, to be updated to the new Specification version with equivalent semantics. Such an update MUST only require changing the `openapi` property to the new minor version. For example, a valid OpenAPI 3.0.2 document, upon changing its `openapi` property to `3.1.0`, SHALL be a valid OpenAPI 3.1.0 document, semantically equivalent to the original OpenAPI 3.0.2 document. New minor versions of the OpenAPI Specification MUST be written to ensure this form of backward compatibility. An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.) ### Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: ```json { "field": [ 1, 2, 3 ] } ``` All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](https://json-schema.org) definitions. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. Primitives have an optional modifier property: `format`. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification. Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. The formats defined by the OAS are: [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments ------ | -------- | -------- `integer` | `int32` | signed 32 bits `integer` | `int64` | signed 64 bits (a.k.a long) `number` | `float` | | `number` | `double` | | `string` | | | `string` | `byte` | base64 encoded characters `string` | `binary` | any sequence of octets `boolean` | | | `string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) `string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject). ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object This is the root document object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Info Object The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the API. description | `string` | A short description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example ```json { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", "termsOfService": "http://example.com/terms/", "contact": { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Sample Pet Store App description: This is a sample server for a pet store. termsOfService: http://example.com/terms/ contact: name: API Support url: http://www.example.com/support email: support@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example ```json { "name": "API Support", "url": "http://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support url: http://www.example.com/support email: support@example.com ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. url | `string` | A URL to the license used for the API. MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example ```json { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } ``` ```yaml name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html ``` #### Server Object An object representing a Server. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", "description": "Development server" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): ```json { "servers": [ { "url": "https://development.gigantic-server.com/v1", "description": "Development server" }, { "url": "https://staging.gigantic-server.com/v1", "description": "Staging server" }, { "url": "https://api.gigantic-server.com/v1", "description": "Production server" } ] } ``` ```yaml servers: - url: https://development.gigantic-server.com/v1 description: Development server - url: https://staging.gigantic-server.com/v1 description: Staging server - url: https://api.gigantic-server.com/v1 description: Production server ``` The following shows how variables can be used for a server configuration: ```json { "servers": [ { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", "variables": { "username": { "default": "demo", "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" }, "port": { "enum": [ "8443", "443" ], "default": "8443" }, "basePath": { "default": "v2" } } } ] } ``` ```yaml servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server variables: username: # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - '8443' - '443' default: '8443' basePath: # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` #### Server Variable Object An object representing a Server Variable for server URL template substitution. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values. description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Components Object Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. ##### Fixed Fields Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```json "components": { "schemas": { "GeneralError": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } }, "parameters": { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "schema": { "type": "integer", "format": "int32" } }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "schema" : { "type": "integer", "format": "int32" } } }, "responses": { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "http://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } } } ``` ```yaml components: schemas: GeneralError: type: object properties: code: type: integer format: int32 message: type: string Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string parameters: skipParam: name: skip in: query description: number of items to skip required: true schema: type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true schema: type: integer format: int32 responses: NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' securitySchemes: api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 flows: implicit: authorizationUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Paths Object Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Templating Matching Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: ``` /pets/{petId} /pets/mine ``` The following paths are considered identical and invalid: ``` /pets/{petId} /pets/{name} ``` The following may lead to ambiguous resolution: ``` /{entity}/me /books/{id} ``` ##### Paths Object Example ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to responses: '200': description: A list of pets. content: application/json: schema: type: array items: $ref: '#/components/schemas/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. summary| `string` | An optional, string summary, intended to apply to all operations in this path. description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Item Object Example ```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "responses": { "200": { "description": "pet response", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "error payload", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "simple" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById responses: '200': description: pet response content: '*/*' : schema: type: array items: $ref: '#/components/schemas/Pet' default: description: error payload content: 'text/html': schema: $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true schema: type: array items: type: string style: simple ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers. responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example ```json { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "operationId": "updatePetWithForm", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "description": "Updated name of the pet", "type": "string" }, "status": { "description": "Updated status of the pet", "type": "string" } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Pet updated.", "content": { "application/json": {}, "application/xml": {} } }, "405": { "description": "Method Not Allowed", "content": { "application/json": {}, "application/xml": {} } } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: string requestBody: content: 'application/x-www-form-urlencoded': schema: properties: name: description: Updated name of the pet type: string status: description: Updated status of the pet type: string required: - status responses: '200': description: Pet updated. content: 'application/json': {} 'application/xml': {} '405': description: Method Not Allowed content: 'application/json': {} 'application/xml': {} security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example ```json { "description": "Find more info here", "url": "https://example.com" } ``` ```yaml description: Find more info here url: https://example.com ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. 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. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- 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`. 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`. 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`. schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter. example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that 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. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- 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. ##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `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. simple | `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. spaceDelimited | `array` | `query` | Space separated array values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array` | `query` | Pipe separated array values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. ##### Style Examples Assume a parameter named `color` has one of the following values: ``` string -> "blue" array -> ["blue","black","brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` The following table shows examples of rendering differences for each value. [`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | -------- | ------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200\|B\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: ```json { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "style": "simple" } ``` ```yaml name: token in: header description: token to be passed as a header required: true schema: type: array items: type: integer format: int64 style: simple ``` A path parameter of a string value: ```json { "name": "username", "in": "path", "description": "username to fetch", "required": true, "schema": { "type": "string" } } ``` ```yaml name: username in: path description: username to fetch required: true schema: type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```json { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ``` ```yaml name: id in: query description: ID of the object to fetch required: false schema: type: array items: type: string style: form explode: true ``` A free-form query parameter, allowing undefined parameters of a specific type: ```json { "in": "query", "name": "freeForm", "schema": { "type": "object", "additionalProperties": { "type": "integer" }, }, "style": "form" } ``` ```yaml in: query name: freeForm schema: type: object additionalProperties: type: integer style: form ``` A complex parameter using `content` to define serialization: ```json { "in": "query", "name": "coordinates", "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "long" ], "properties": { "lat": { "type": "number" }, "long": { "type": "number" } } } } } } ``` ```yaml in: query name: coordinates content: application/json: schema: type: object required: - lat - long properties: lat: type: number long: type: number ``` #### Request Body Object Describes a single request body. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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/* required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Request Body Examples A request body with a referenced model definition. ```json { "description": "user to add to the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User Example", "externalValue": "http://foo.bar/examples/user-example.json" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User example in XML", "externalValue": "http://foo.bar/examples/user-example.xml" } } }, "text/plain": { "examples": { "user" : { "summary": "User example in Plain text", "externalValue": "http://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { "summary": "User example in other format", "externalValue": "http://foo.bar/examples/user-example.whatever" } } } } } ``` ```yaml description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example externalValue: 'http://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example in XML externalValue: 'http://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in text plain format externalValue: 'http://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format externalValue: 'http://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: ```json { "description": "user to add to the system", "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } ``` ```yaml description: user to add to the system required: true content: text/plain: schema: type: array items: type: string ``` #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, or parameter. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Media Type Examples ```json { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", "value": { "name": "Fluffy", "petType": "Cat", "color": "White", "gender": "male", "breed": "Persian" } }, "dog": { "summary": "An example of a dog with a cat's name", "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" }, "frog": { "$ref": "#/components/examples/frog-example" } } } } } ``` ```yaml application/json: schema: $ref: "#/components/schemas/Pet" examples: cat: summary: An example of a cat value: name: Fluffy petType: Cat color: White gender: male breed: Persian dog: summary: An example of a dog with a cat's name value: name: Puma petType: Dog color: Black gender: Female breed: Mixed frog: $ref: "#/components/examples/frog-example" ``` ##### Considerations for File Uploads In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically: ```yaml # content transferred with base64 encoding schema: type: string format: base64 ``` ```yaml # content transferred in binary (octet-stream): schema: type: string format: binary ``` These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: ```yaml requestBody: content: application/octet-stream: schema: # a binary file of any type type: string format: binary ``` In addition, specific media types MAY be specified: ```yaml # multiple, specific media types may be specified: requestBody: content: # a binary file of type png or jpeg 'image/jpeg': schema: type: string format: binary 'image/png': schema: type: string format: binary ``` To upload multiple files, a `multipart` media type MUST be used: ```yaml requestBody: content: multipart/form-data: schema: properties: # The property name 'file' will be used for all files. file: type: array items: type: string format: binary ``` ##### Support for x-www-form-urlencoded Request Bodies To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following definition may be used: ```yaml requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: id: type: string format: uuid address: # complex types are stringified to support RFC 1866 type: object properties: {} ``` In 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. When 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`. ##### Special Considerations for `multipart` Content It 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. When 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`: * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` * If the property is complex, or an array of complex values, the default Content-Type is `application/json` * 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` Examples: ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: type: string format: uuid address: # default Content-Type for objects is `application/json` type: object properties: {} profileImage: # default Content-Type for string/binary is `application/octet-stream` type: string format: binary children: # default Content-Type for arrays is based on the `inner` type (text/plain here) type: array items: type: string addresses: # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) type: array items: type: '#/components/schemas/Address' ``` An `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. #### Encoding Object A single encoding definition applied to a single schema property. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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`. 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`. 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`. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example ```yaml requestBody: content: multipart/mixed: schema: type: object properties: id: # default is text/plain type: string format: uuid address: # default is application/json type: object properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object properties: {} profileImage: # default is application/octet-stream, need to declare an image type only! type: string format: binary encoding: historyMetadata: # require XML Content-Type in utf-8 encoding contentType: application/xml; charset=utf-8 profileImage: # only accept png/jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the specification. The `Responses Object` MUST contain at least one response code, and it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- [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]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Responses Object Example A 200 response for a successful operation and a default response for others (implying an error): ```json { "200": { "description": "a pet to be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } ``` ```yaml '200': description: a pet to be returned content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorModel' ``` #### Response Object Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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. 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/* 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). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples Response of an array of a complex type: ```json { "description": "A complex object array response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VeryComplexType" } } } } } ``` ```yaml description: A complex object array response content: application/json: schema: type: array items: $ref: '#/components/schemas/VeryComplexType' ``` Response with a string type: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string ``` Plain text response with headers: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string", "example": "whoa!" } } }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "schema": { "type": "integer" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer ``` Response with no return value: ```json { "description": "object created" } ``` ```yaml description: object created ``` #### Callback Object A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {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. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Key Expression The 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. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: ```http POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { "failedUrl" : "http://clientdomain.com/failed", "successUrls" : [ "http://clientdomain.com/fast", "http://clientdomain.com/medium", "http://clientdomain.com/slow" ] } 201 Created Location: http://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- $url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent $request.query.queryUrl | http://clientdomain.com/stillrunning $request.header.content-Type | application/json $request.body#/failedUrl | http://clientdomain.com/failed $request.body#/successUrls/2 | http://clientdomain.com/medium $response.header.Location | http://example.org/subscription/1 ##### Callback Object Examples The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. ```yaml myCallback: '{$request.query.queryUrl}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: callback successfully processed ``` The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body. ```yaml transactionCallback: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: callback successfully processed ``` #### Example Object ##### Fixed Fields Field Name | Type | Description ---|:---:|--- summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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. 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Examples In a request body: ```yaml requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: summary: This is an example in XML externalValue: 'http://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example externalValue: 'http://foo.bar/examples/address-example.txt' ``` In a parameter: ```yaml parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' examples: zip-example: $ref: '#/components/examples/zip-example' ``` In a response: ```yaml responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' examples: confirmation-success: $ref: '#/components/examples/confirmation-success' ``` #### Link Object The `Link object` represents a possible design-time link for a response. The 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. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For 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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- operationRef | `string` | A relative or absolute URI 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. 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. 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). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. ```yaml paths: /users/{id}: parameters: - name: id in: path required: true description: the user identifier, as userId schema: type: string get: responses: '200': description: the user being returned content: application/json: schema: type: object properties: uuid: # the unique user id type: string format: uuid links: address: # the target link operationId operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` userId: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: - name: userid in: path required: true description: the user identifier, as userId schema: type: string # linked operation get: operationId: getUserAddress responses: '200': description: the user's address ``` When a runtime expression fails to evaluate, no parameter value is passed to the target operation. Values from the response body can be used to drive a linked operation. ```yaml links: address: operationId: getUserAddressByUUID parameters: # get the `uuid` field from the `uuid` field in the response body userUuid: $response.body#/uuid ``` Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional field in an [Operation Object](#operationObject)), references MAY also be made through a relative `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` or an absolute `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. ##### Runtime Expressions Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ```abnf expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" json-pointer ] json-pointer = *( "/" reference-token ) reference-token = *( unescaped / escaped ) unescaped = %x00-2E / %x30-7D / %x7F-10FFFF ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' escaped = "~" ( "0" / "1" ) ; representing '~' and '/', respectively name = *( CHAR ) token = 1*tchar tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` Here, `json-pointer` is taken from [RFC 6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC 7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: ##### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request 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. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). ##### Header Object Example A simple header of type `integer`: ```json { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } } ``` ```yaml description: The number of allowed requests in the current period schema: type: integer ``` #### Tag Object Adds metadata to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example ```json { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. The 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. For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. ##### Reference Object Example ```json { "$ref": "#/components/schemas/Pet" } ``` ```yaml $ref: '#/components/schemas/Pet' ``` ##### Relative Schema Document Example ```json { "$ref": "Pet.json" } ``` ```yaml $ref: Pet.yaml ``` ##### Relative Documents With Embedded Schema Example ```json { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: definitions.yaml#/Pet ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the [JSON Schema Specification Wright Draft 00](https://json-schema.org/). For 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). Unless stated otherwise, the property definitions follow the JSON Schema. ##### Properties The following properties are taken directly from the JSON Schema definition and follow the same specifications: - title - multipleOf - maximum - exclusiveMaximum - minimum - exclusiveMinimum - maxLength - minLength - pattern (This string SHOULD be a valid regular expression, according to the [Ecma-262 Edition 5.1 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-15.10.1) dialect) - maxItems - minItems - uniqueItems - maxProperties - minProperties - required - enum The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. - type - Value MUST be a string. Multiple types via an array are not supported. - allOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - oneOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - anyOf - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. - 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`. - properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced). - additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`. - description - [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. - 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. - 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`. Alternatively, 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. Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported. Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`. 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. readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ##### Schema Object Examples ###### Primitive Sample ```json { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/components/schemas/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```json { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```json { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/components/schemas/ComplexModel' ``` ###### Model with Example ```json { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```json { "components": { "schemas": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/components/schemas/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } } ``` ```yaml components: schemas: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```json { "components": { "schemas": { "Pet": { "type": "object", "discriminator": { "propertyName": "petType" }, "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } } ``` ```yaml components: schemas: Pet: type: object discriminator: propertyName: petType properties: name: type: string petType: type: string required: - name - petType Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' ``` which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: petType ``` The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: ```json { "id": 12345, "petType": "Cat" } ``` Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. For example: ```yaml components: schemas: Pet: type: object required: - petType properties: petType: type: string discriminator: propertyName: petType mapping: dog: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean ``` a payload like this: ```json { "petType": "Cat", "name": "misty" } ``` will indicate that the `Cat` schema be used. Likewise this schema: ```json { "petType": "dog", "bark": "soft" } ``` will map to `Dog` because of the definition in the `mappings` element. #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```json { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```json { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```json { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "http://example.com/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: http://example.com/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the naming problem in the example above, the following definition can be used: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example ###### Basic Authentication Sample ```json { "type": "http", "scheme": "basic" } ``` ```yaml type: http scheme: basic ``` ###### API Key Sample ```json { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### JWT Bearer Sample ```json { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", } ``` ```yaml type: http scheme: bearer bearerFormat: JWT ``` ###### Implicit OAuth2 Sample ```json { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### OAuth Flows Object Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### OAuth Flow Object Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples ```JSON { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```json { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```json { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ###### Optional OAuth2 Security Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object: ```json { "security": [ {}, { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml security: - {} - petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples of this: 1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification OpenAPI-Specification-3.1.0/versions/3.1.0.md000066400000000000000000004005051401301652500203560ustar00rootroot00000000000000# OpenAPI Specification #### Version 3.1.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. ## Table of Contents - [Definitions](#definitions) - [OpenAPI Document](#oasDocument) - [Path Templating](#pathTemplating) - [Media Types](#mediaTypes) - [HTTP Status Codes](#httpCodes) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - [Relative References In URIs](#relativeReferencesURI) - [Relative References In URLs](#relativeReferencesURL) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) - [Contact Object](#contactObject) - [License Object](#licenseObject) - [Server Object](#serverObject) - [Server Variable Object](#serverVariableObject) - [Components Object](#componentsObject) - [Paths Object](#pathsObject) - [Path Item Object](#pathItemObject) - [Operation Object](#operationObject) - [External Documentation Object](#externalDocumentationObject) - [Parameter Object](#parameterObject) - [Request Body Object](#requestBodyObject) - [Media Type Object](#mediaTypeObject) - [Encoding Object](#encodingObject) - [Responses Object](#responsesObject) - [Response Object](#responseObject) - [Callback Object](#callbackObject) - [Example Object](#exampleObject) - [Link Object](#linkObject) - [Header Object](#headerObject) - [Tag Object](#tagObject) - [Reference Object](#referenceObject) - [Schema Object](#schemaObject) - [Discriminator Object](#discriminatorObject) - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [OAuth Flows Object](#oauthFlowsObject) - [OAuth Flow Object](#oauthFlowObject) - [Security Requirement Object](#securityRequirementObject) - [Specification Extensions](#specificationExtensions) - [Security Filtering](#securityFiltering) - [Appendix A: Revision History](#revisionHistory) ## Definitions ##### OpenAPI Document A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification. ##### Path Templating Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required. The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by [RFC3986](https://tools.ietf.org/html/rfc3986#section-3): forward slashes (`/`), question marks (`?`), or hashes (`#`). ##### Media Types Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838). Some examples of possible media type definitions: ``` text/plain; charset=utf-8 application/json application/vnd.github+json application/vnd.github.v3+json application/vnd.github.v3.raw+json application/vnd.github.v3.text+json application/vnd.github.v3.html+json application/vnd.github.v3.full+json application/vnd.github.v3.diff application/vnd.github.v3.patch ``` ##### HTTP Status Codes The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). ## Specification ### Versions The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example `3.1`) SHALL designate the OAS feature set. *`.patch`* versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.1.0` and `3.1.1` for example. Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the version of the OAS that it uses. ### Format An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format. For example, if a field has an array value, the JSON array representation will be used: ```json { "field": [ 1, 2, 3 ] } ``` All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields MUST have unique names within the containing object. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). **Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML. ### Document Structure An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [`Reference Objects`](#referenceObject) and [`Schema Object`](#schemaObject) `$ref` keywords are used. It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. ### Data Types Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. OAS defines additional formats to provide fine detail for primitive data types. The formats defined by the OAS are: [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments ------ | -------- | -------- `integer` | `int32` | signed 32 bits `integer` | `int64` | signed 64 bits (a.k.a long) `number` | `float` | | `number` | `double` | | `string` | `password` | A hint to UIs to obscure input. ### Rich Text Formatting Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. ### Relative References in URIs Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Relative references, including those in [`Reference Objects`](#referenceObject), [`PathItem Object`](#pathItemObject) `$ref` fields, [`Link Object`](#linkObject) `operationRef` fields and [`Example Object`](#exampleObject) `externalValue` fields, are resolved using the referring document as the Base URI according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.2). If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901). Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2). If no parent schema contains an `$id`, then the Base URI MUST be determined according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1). ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URL. Note that these themselves MAY be relative to the referring document. ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### OpenAPI Object This is the root object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. jsonSchemaDialect | `string` | The default value for the `$schema` keyword within [Schema Objects](#schemaObject) contained within this OAS document. This MUST be in the form of a URI. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | The available paths and operations for the API. webhooks | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available. components | [Components Object](#componentsObject) | An element to hold various schemas for the document. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array. tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Info Object The object provides metadata about the API. The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the API. summary | `string` | A short summary of the API. description | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example ```json { "title": "Sample Pet Store App", "summary": "A pet store manager.", "description": "This is a sample server for a pet store.", "termsOfService": "https://example.com/terms/", "contact": { "name": "API Support", "url": "https://www.example.com/support", "email": "support@example.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1" } ``` ```yaml title: Sample Pet Store App summary: A pet store manager. description: This is a sample server for a pet store. termsOfService: https://example.com/terms/ contact: name: API Support url: https://www.example.com/support email: support@example.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.1 ``` #### Contact Object Contact information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. url | `string` | The URL pointing to the contact information. This MUST be in the form of a URL. email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example ```json { "name": "API Support", "url": "https://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support url: https://www.example.com/support email: support@example.com ``` #### License Object License information for the exposed API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field. url | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example ```json { "name": "Apache 2.0", "identifier": "Apache-2.0" } ``` ```yaml name: Apache 2.0 identifier: Apache-2.0 ``` #### Server Object An object representing a Server. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Server Object Example A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", "description": "Development server" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers): ```json { "servers": [ { "url": "https://development.gigantic-server.com/v1", "description": "Development server" }, { "url": "https://staging.gigantic-server.com/v1", "description": "Staging server" }, { "url": "https://api.gigantic-server.com/v1", "description": "Production server" } ] } ``` ```yaml servers: - url: https://development.gigantic-server.com/v1 description: Development server - url: https://staging.gigantic-server.com/v1 description: Staging server - url: https://api.gigantic-server.com/v1 description: Production server ``` The following shows how variables can be used for a server configuration: ```json { "servers": [ { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", "variables": { "username": { "default": "demo", "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" }, "port": { "enum": [ "8443", "443" ], "default": "8443" }, "basePath": { "default": "v2" } } } ] } ``` ```yaml servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server variables: username: # note! no enum here means it is an open value default: demo description: this value is assigned by the service provider, in this example `gigantic-server.com` port: enum: - '8443' - '443' default: '8443' basePath: # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` default: v2 ``` #### Server Variable Object An object representing a Server Variable for server URL template substitution. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty. default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value MUST exist in the enum's values. description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### Components Object Holds a set of reusable objects for different aspects of the OAS. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. ##### Fixed Fields Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject). headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject). callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject). pathItems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```json "components": { "schemas": { "GeneralError": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } } }, "parameters": { "skipParam": { "name": "skip", "in": "query", "description": "number of items to skip", "required": true, "schema": { "type": "integer", "format": "int32" } }, "limitParam": { "name": "limit", "in": "query", "description": "max records to return", "required": true, "schema" : { "type": "integer", "format": "int32" } } }, "responses": { "NotFound": { "description": "Entity not found." }, "IllegalInput": { "description": "Illegal input for operation." }, "GeneralError": { "description": "General Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralError" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "api_key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } } } ``` ```yaml components: schemas: GeneralError: type: object properties: code: type: integer format: int32 message: type: string Category: type: object properties: id: type: integer format: int64 name: type: string Tag: type: object properties: id: type: integer format: int64 name: type: string parameters: skipParam: name: skip in: query description: number of items to skip required: true schema: type: integer format: int32 limitParam: name: limit in: query description: max records to return required: true schema: type: integer format: int32 responses: NotFound: description: Entity not found. IllegalInput: description: Illegal input for operation. GeneralError: description: General Error content: application/json: schema: $ref: '#/components/schemas/GeneralError' securitySchemes: api_key: type: apiKey name: api_key in: header petstore_auth: type: oauth2 flows: implicit: authorizationUrl: https://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Paths Object Holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering). ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- /{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a forward slash (`/`). The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Templating Matching Assuming the following paths, the concrete definition, `/pets/mine`, will be matched first if used: ``` /pets/{petId} /pets/mine ``` The following paths are considered identical and invalid: ``` /pets/{petId} /pets/{name} ``` The following may lead to ambiguous resolution: ``` /{entity}/me /books/{id} ``` ##### Paths Object Example ```json { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } ``` ```yaml /pets: get: description: Returns all pets from the system that the user has access to responses: '200': description: A list of pets. content: application/json: schema: type: array items: $ref: '#/components/schemas/pet' ``` #### Path Item Object Describes the operations available on a single path. A Path Item MAY be empty, due to [ACL constraints](#securityFiltering). The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relativeReferencesURI). summary| `string` | An optional, string summary, intended to apply to all operations in this path. description | `string` | An optional, string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. put | [Operation Object](#operationObject) | A definition of a PUT operation on this path. post | [Operation Object](#operationObject) | A definition of a POST operation on this path. delete | [Operation Object](#operationObject) | A definition of a DELETE operation on this path. options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path. servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Path Item Object Example ```json { "get": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "getPetsById", "responses": { "200": { "description": "pet response", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } } } } }, "default": { "description": "error payload", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } }, "parameters": [ { "name": "id", "in": "path", "description": "ID of pet to use", "required": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "simple" } ] } ``` ```yaml get: description: Returns pets based on ID summary: Find pets by ID operationId: getPetsById responses: '200': description: pet response content: '*/*' : schema: type: array items: $ref: '#/components/schemas/Pet' default: description: error payload content: 'text/html': schema: $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path description: ID of pet to use required: true schema: type: array items: type: string style: simple ``` #### Operation Object Describes a single API operation on a path. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- tags | [`string`] | A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier. summary | `string` | A short summary of what the operation does. description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. responses | [Responses Object](#responsesObject) | The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example ```json { "tags": [ "pet" ], "summary": "Updates a pet in the store with form data", "operationId": "updatePetWithForm", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet that needs to be updated", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "description": "Updated name of the pet", "type": "string" }, "status": { "description": "Updated status of the pet", "type": "string" } }, "required": ["status"] } } } }, "responses": { "200": { "description": "Pet updated.", "content": { "application/json": {}, "application/xml": {} } }, "405": { "description": "Method Not Allowed", "content": { "application/json": {}, "application/xml": {} } } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml tags: - pet summary: Updates a pet in the store with form data operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: string requestBody: content: 'application/x-www-form-urlencoded': schema: type: object properties: name: description: Updated name of the pet type: string status: description: Updated status of the pet type: string required: - status responses: '200': description: Pet updated. content: 'application/json': {} 'application/xml': {} '405': description: Method Not Allowed content: 'application/json': {} 'application/xml': {} security: - petstore_auth: - write:pets - read:pets ``` #### External Documentation Object Allows referencing an external resource for extended documentation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. url | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example ```json { "description": "Find more info here", "url": "https://example.com" } ``` ```yaml description: Find more info here url: https://example.com ``` #### Parameter Object Describes a single operation parameter. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). ##### Parameter Locations There are four possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. * cookie - Used to pass a specific cookie value to the API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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`. deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. 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. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision. The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter. Field Name | Type | Description ---|:---:|--- 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`. 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`. 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`. schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter. example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that 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. examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema. For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter. A parameter MUST contain either a `schema` property, or a `content` property, but not both. When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- 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. ##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. `style` | [`type`](#dataTypes) | `in` | Comments ----------- | ------ | -------- | -------- matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5) form | `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. simple | `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. spaceDelimited | `array`, `object` | `query` | Space separated array or object values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0. pipeDelimited | `array`, `object` | `query` | Pipe separated array or object values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0. deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters. ##### Style Examples Assume a parameter named `color` has one of the following values: ``` string -> "blue" array -> ["blue","black","brown"] object -> { "R": 100, "G": 200, "B": 150 } ``` The following table shows examples of rendering differences for each value. [`style`](#styleValues) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | -------- | ------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 label | false | . | .blue | .blue.black.brown | .R.100.G.200.B.150 label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150 form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150 spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20B%20150 pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200\|B\|150 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150 This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Examples A header parameter with an array of 64 bit integer numbers: ```json { "name": "token", "in": "header", "description": "token to be passed as a header", "required": true, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "style": "simple" } ``` ```yaml name: token in: header description: token to be passed as a header required: true schema: type: array items: type: integer format: int64 style: simple ``` A path parameter of a string value: ```json { "name": "username", "in": "path", "description": "username to fetch", "required": true, "schema": { "type": "string" } } ``` ```yaml name: username in: path description: username to fetch required: true schema: type: string ``` An optional query parameter of a string value, allowing multiple values by repeating the query parameter: ```json { "name": "id", "in": "query", "description": "ID of the object to fetch", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true } ``` ```yaml name: id in: query description: ID of the object to fetch required: false schema: type: array items: type: string style: form explode: true ``` A free-form query parameter, allowing undefined parameters of a specific type: ```json { "in": "query", "name": "freeForm", "schema": { "type": "object", "additionalProperties": { "type": "integer" }, }, "style": "form" } ``` ```yaml in: query name: freeForm schema: type: object additionalProperties: type: integer style: form ``` A complex parameter using `content` to define serialization: ```json { "in": "query", "name": "coordinates", "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "long" ], "properties": { "lat": { "type": "number" }, "long": { "type": "number" } } } } } } ``` ```yaml in: query name: coordinates content: application/json: schema: type: object required: - lat - long properties: lat: type: number long: type: number ``` #### Request Body Object Describes a single request body. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A brief description of the request body. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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/* required | `boolean` | Determines if the request body is required in the request. Defaults to `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Request Body Examples A request body with a referenced model definition. ```json { "description": "user to add to the system", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User Example", "externalValue": "https://foo.bar/examples/user-example.json" } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/User" }, "examples": { "user" : { "summary": "User example in XML", "externalValue": "https://foo.bar/examples/user-example.xml" } } }, "text/plain": { "examples": { "user" : { "summary": "User example in Plain text", "externalValue": "https://foo.bar/examples/user-example.txt" } } }, "*/*": { "examples": { "user" : { "summary": "User example in other format", "externalValue": "https://foo.bar/examples/user-example.whatever" } } } } } ``` ```yaml description: user to add to the system content: 'application/json': schema: $ref: '#/components/schemas/User' examples: user: summary: User Example externalValue: 'https://foo.bar/examples/user-example.json' 'application/xml': schema: $ref: '#/components/schemas/User' examples: user: summary: User example in XML externalValue: 'https://foo.bar/examples/user-example.xml' 'text/plain': examples: user: summary: User example in Plain text externalValue: 'https://foo.bar/examples/user-example.txt' '*/*': examples: user: summary: User example in other format externalValue: 'https://foo.bar/examples/user-example.whatever' ``` A body parameter that is an array of string values: ```json { "description": "user to add to the system", "required": true, "content": { "text/plain": { "schema": { "type": "array", "items": { "type": "string" } } } } } ``` ```yaml description: user to add to the system required: true content: text/plain: schema: type: array items: type: string ``` #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the content of the request, response, or parameter. example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. 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` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema. 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`. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Media Type Examples ```json { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" }, "examples": { "cat" : { "summary": "An example of a cat", "value": { "name": "Fluffy", "petType": "Cat", "color": "White", "gender": "male", "breed": "Persian" } }, "dog": { "summary": "An example of a dog with a cat's name", "value" : { "name": "Puma", "petType": "Dog", "color": "Black", "gender": "Female", "breed": "Mixed" }, "frog": { "$ref": "#/components/examples/frog-example" } } } } } ``` ```yaml application/json: schema: $ref: "#/components/schemas/Pet" examples: cat: summary: An example of a cat value: name: Fluffy petType: Cat color: White gender: male breed: Persian dog: summary: An example of a dog with a cat's name value: name: Puma petType: Dog color: Black gender: Female breed: Mixed frog: $ref: "#/components/examples/frog-example" ``` ##### Considerations for File Uploads In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. In contrast with the 3.0 specification, the `format` keyword has no effect on the content-encoding of the schema. JSON Schema offers a `contentEncoding` keyword, which may be used to specify the `Content-Encoding` for the schema. The `contentEncoding` keyword supports all encodings defined in [RFC4648](https://tools.ietf.org/html/rfc4648), including "base64" and "base64url", as well as "quoted-printable" from [RFC2045](https://tools.ietf.org/html/rfc2045#section-6.7). The encoding specified by the `contentEncoding` keyword is independent of an encoding specified by the `Content-Type` header in the request or response or metadata of a multipart body -- when both are present, the encoding specified in the `contentEncoding` is applied first and then the encoding specified in the `Content-Type` header. JSON Schema also offers a `contentMediaType` keyword. However, when the media type is already specified by the Media Type Object's key, or by the `contentType` field of an [Encoding Object](#encodingObject), the `contentMediaType` keyword SHALL be ignored if present. Examples: Content transferred in binary (octet-stream) MAY omit `schema`: ```yaml # a PNG image as a binary file: content: image/png: {} ``` ```yaml # an arbitrary binary file: content: application/octet-stream: {} ``` Binary content transferred with base64 encoding: ```yaml content: image/png: schema: type: string contentMediaType: image/png contentEncoding: base64 ``` Note that the `Content-Type` remains `image/png`, describing the semantics of the payload. The JSON Schema `type` and `contentEncoding` fields explain that the payload is transferred as text. The JSON Schema `contentMediaType` is technically redundant, but can be used by JSON Schema tools that may not be aware of the OpenAPI context. These examples apply to either input payloads of file uploads or response payloads. A `requestBody` for submitting a file in a `POST` operation may look like the following example: ```yaml requestBody: content: application/octet-stream: {} ``` In addition, specific media types MAY be specified: ```yaml # multiple, specific media types may be specified: requestBody: content: # a binary file of type png or jpeg image/jpeg: {} image/png: {} ``` To upload multiple files, a `multipart` media type MUST be used: ```yaml requestBody: content: multipart/form-data: schema: properties: # The property name 'file' will be used for all files. file: type: array items: {} ``` As seen in the section on `multipart/form-data` below, the empty schema for `items` indicates a media type of `application/octet-stream`. ##### Support for x-www-form-urlencoded Request Bodies To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following definition may be used: ```yaml requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: id: type: string format: uuid address: # complex types are stringified to support RFC 1866 type: object properties: {} ``` In 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. When 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`. ##### Special Considerations for `multipart` Content It 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. In a `multipart/form-data` request body, each schema property, or each element of a schema array property, takes a section in the payload with an internal header as defined by [RFC7578](https://tools.ietf.org/html/rfc7578). The serialization strategy for each property of a `multipart/form-data` request body can be specified in an associated [`Encoding Object`](#encodingObject). When 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`: * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain` * If the property is complex, or an array of complex values, the default Content-Type is `application/json` * If the property is a `type: string` with a `contentEncoding`, the default Content-Type is `application/octet-stream` Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. Examples: ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: type: string format: uuid address: # default Content-Type for objects is `application/json` type: object properties: {} profileImage: # Content-Type for application-level encoded resource is `text/plain` type: string contentMediaType: image/png contentEncoding: base64 children: # default Content-Type for arrays is based on the _inner_ type (`text/plain` here) type: array items: type: string addresses: # default Content-Type for arrays is based on the _inner_ type (object shown, so `application/json` in this example) type: array items: type: object $ref: '#/components/schemas/Address' ``` An `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. #### Encoding Object A single encoding definition applied to a single schema property. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `object` - `application/json`; for `array` – the default is defined based on the inner type; for all other cases the default is `application/octet-stream`. 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. 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`. 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` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored. 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` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored. 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` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Encoding Object Example ```yaml requestBody: content: multipart/form-data: schema: type: object properties: id: # default is text/plain type: string format: uuid address: # default is application/json type: object properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object properties: {} profileImage: {} encoding: historyMetadata: # require XML Content-Type in utf-8 encoding contentType: application/xml; charset=utf-8 profileImage: # only accept png/jpeg contentType: image/png, image/jpeg headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer ``` #### Responses Object A container for the expected responses of an operation. The container maps a HTTP response code to the expected response. The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be known in advance. However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes that are not covered individually by the `Responses Object`. The `Responses Object` MUST contain at least one response code, and if only one response code is provided it SHOULD be the response for a successful operation call. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- [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. 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]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Responses Object Example A 200 response for a successful operation and a default response for others (implying an error): ```json { "200": { "description": "a pet to be returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } } ``` ```yaml '200': description: a pet to be returned content: application/json: schema: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorModel' ``` #### Response Object Describes a single response from an API Operation, including design-time, static `links` to operations based on the response. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | **REQUIRED**. A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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. 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/* 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). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Response Object Examples Response of an array of a complex type: ```json { "description": "A complex object array response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VeryComplexType" } } } } } ``` ```yaml description: A complex object array response content: application/json: schema: type: array items: $ref: '#/components/schemas/VeryComplexType' ``` Response with a string type: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string ``` Plain text response with headers: ```json { "description": "A simple string response", "content": { "text/plain": { "schema": { "type": "string", "example": "whoa!" } } }, "headers": { "X-Rate-Limit-Limit": { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Remaining": { "description": "The number of remaining requests in the current period", "schema": { "type": "integer" } }, "X-Rate-Limit-Reset": { "description": "The number of seconds left in the current period", "schema": { "type": "integer" } } } } ``` ```yaml description: A simple string response content: text/plain: schema: type: string example: 'whoa!' headers: X-Rate-Limit-Limit: description: The number of allowed requests in the current period schema: type: integer X-Rate-Limit-Remaining: description: The number of remaining requests in the current period schema: type: integer X-Rate-Limit-Reset: description: The number of seconds left in the current period schema: type: integer ``` Response with no return value: ```json { "description": "object created" } ``` ```yaml description: object created ``` #### Callback Object A map of possible out-of band callbacks related to the parent operation. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses. The key value used to identify the path item object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. To describe incoming requests from the API provider independent from another API call, use the [`webhooks`](#oasWebhooks) field. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {expression} | [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject) | A Path Item Object, or a reference to one, used to define a callback request and expected responses. A [complete example](../examples/v3.0/callback-example.yaml) is available. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Key Expression The 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. A simple example might be `$request.body#/url`. However, using a [runtime expression](#runtimeExpression) the complete HTTP message can be accessed. This includes accessing any part of a body that a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) can reference. For example, given the following HTTP request: ```http POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { "failedUrl" : "https://clientdomain.com/failed", "successUrls" : [ "https://clientdomain.com/fast", "https://clientdomain.com/medium", "https://clientdomain.com/slow" ] } 201 Created Location: https://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- $url | https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent $request.query.queryUrl | https://clientdomain.com/stillrunning $request.header.content-Type | application/json $request.body#/failedUrl | https://clientdomain.com/failed $request.body#/successUrls/2 | https://clientdomain.com/medium $response.header.Location | https://example.org/subscription/1 ##### Callback Object Examples The following example uses the user provided `queryUrl` query string parameter to define the callback URL. This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook. ```yaml myCallback: '{$request.query.queryUrl}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: callback successfully processed ``` The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the `id` and `email` property in the request body. ```yaml transactionCallback: 'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}': post: requestBody: description: Callback payload content: 'application/json': schema: $ref: '#/components/schemas/SomePayload' responses: '200': description: callback successfully processed ``` #### Example Object ##### Fixed Fields Field Name | Type | Description ---|:---:|--- summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. 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. externalValue | `string` | A URI 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. See the rules for resolving [Relative References](#relativeReferencesURI). This object MAY be extended with [Specification Extensions](#specificationExtensions). In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible. ##### Example Object Examples In a request body: ```yaml requestBody: content: 'application/json': schema: $ref: '#/components/schemas/Address' examples: foo: summary: A foo example value: {"foo": "bar"} bar: summary: A bar example value: {"bar": "baz"} 'application/xml': examples: xmlExample: summary: This is an example in XML externalValue: 'https://example.org/examples/address-example.xml' 'text/plain': examples: textExample: summary: This is a text example externalValue: 'https://foo.bar/examples/address-example.txt' ``` In a parameter: ```yaml parameters: - name: 'zipCode' in: 'query' schema: type: 'string' format: 'zip-code' examples: zip-example: $ref: '#/components/examples/zip-example' ``` In a response: ```yaml responses: '200': description: your car appointment has been booked content: application/json: schema: $ref: '#/components/schemas/SuccessResponse' examples: confirmation-success: $ref: '#/components/examples/confirmation-success' ``` #### Link Object The `Link object` represents a possible design-time link for a response. The 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. Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response. For 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. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- operationRef | `string` | A relative or absolute URI 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. See the rules for resolving [Relative References](#relativeReferencesURI). 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. 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). requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, the `operationRef` syntax is preferred for OpenAPI documents with external references. ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. ```yaml paths: /users/{id}: parameters: - name: id in: path required: true description: the user identifier, as userId schema: type: string get: responses: '200': description: the user being returned content: application/json: schema: type: object properties: uuid: # the unique user id type: string format: uuid links: address: # the target link operationId operationId: getUserAddress parameters: # get the `id` field from the request path parameter named `id` userId: $request.path.id # the path item of the linked operation /users/{userid}/address: parameters: - name: userid in: path required: true description: the user identifier, as userId schema: type: string # linked operation get: operationId: getUserAddress responses: '200': description: the user's address ``` When a runtime expression fails to evaluate, no parameter value is passed to the target operation. Values from the response body can be used to drive a linked operation. ```yaml links: address: operationId: getUserAddressByUUID parameters: # get the `uuid` field from the `uuid` field in the response body userUuid: $response.body#/uuid ``` Clients follow all links at their discretion. Neither permissions, nor the capability to make a successful call to that link, is guaranteed solely by the existence of a relationship. ##### OperationRef Examples As references to `operationId` MAY NOT be possible (the `operationId` is an optional field in an [Operation Object](#operationObject)), references MAY also be made through a relative `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: '#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` or an absolute `operationRef`: ```yaml links: UserRepositories: # returns array of '#/components/schemas/repository' operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get' parameters: username: $response.body#/username ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when using JSON references. ##### Runtime Expressions Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax ```abnf expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source ) source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" json-pointer ] json-pointer = *( "/" reference-token ) reference-token = *( unescaped / escaped ) unescaped = %x00-2E / %x30-7D / %x7F-10FFFF ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' escaped = "~" ( "0" / "1" ) ; representing '~' and '/', respectively name = *( CHAR ) token = 1*tchar tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` Here, `json-pointer` is taken from [RFC6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: ##### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request 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. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. #### Header Object The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes: 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map. 1. `in` MUST NOT be specified, it is implicitly in `header`. 1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). ##### Header Object Example A simple header of type `integer`: ```json { "description": "The number of allowed requests in the current period", "schema": { "type": "integer" } } ``` ```yaml description: The number of allowed requests in the current period schema: type: integer ``` #### Tag Object Adds metadata to a single tag that is used by the [Operation Object](#operationObject). It is not mandatory to have a Tag Object per tag defined in the Operation Object instances. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example ```json { "name": "pet", "description": "Pets operations" } ``` ```yaml name: pet description: Pets operations ``` #### Reference Object A simple object to allow referencing other components in the OpenAPI document, internally and externally. The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the location of the value being referenced. See the rules for resolving [Relative References](#relativeReferencesURI). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED**. The reference identifier. This MUST be in the form of a URI. summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not allow a `summary` field, then this field has no effect. description | `string` | A description which by default SHOULD override that of the referenced component. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. If the referenced object-type does not allow a `description` field, then this field has no effect. This object cannot be extended with additional properties and any properties added SHALL be ignored. Note that this restriction on additional properties is a difference between Reference Objects and [`Schema Objects`](#schemaObject) that contain a `$ref` keyword. ##### Reference Object Example ```json { "$ref": "#/components/schemas/Pet" } ``` ```yaml $ref: '#/components/schemas/Pet' ``` ##### Relative Schema Document Example ```json { "$ref": "Pet.json" } ``` ```yaml $ref: Pet.yaml ``` ##### Relative Documents With Embedded Schema Example ```json { "$ref": "definitions.json#/Pet" } ``` ```yaml $ref: definitions.yaml#/Pet ``` #### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00). For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00). Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document. ##### Properties The OpenAPI Schema Object [dialect](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.3.3) is defined as requiring the [OAS base vocabulary](#baseVocabulary), in addition to the vocabularies as specified in the JSON Schema draft 2020-12 [general purpose meta-schema](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8). The OpenAPI Schema Object dialect for this version of the specification is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base` (the "OAS dialect schema id"). The following properties are taken from the JSON Schema specification but their definitions have been extended by the OAS: - description - [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. - 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. In addition to the JSON Schema properties comprising the OAS dialect, the Schema Object supports keywords from any other vocabularies, or entirely arbitrary properties. The OpenAPI Specification's base vocabulary is comprised of the following keywords: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- 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. 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. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. This object MAY be extended with [Specification Extensions](#specificationExtensions), though as noted, additional properties MAY omit the `x-` prefix within this object. ###### Composition and Inheritance (Polymorphism) The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. ###### Specifying Schema Dialects It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema. The `$schema` keyword MAY be present in any root Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. This allows use of Schema Objects which comply with other drafts of JSON Schema than the default Draft 2020-12 support. Tooling MUST support the OAS dialect schema id, and MAY support additional values of `$schema`. To allow use of a different default `$schema` value for all Schema Objects contained within an OAS document, a `jsonSchemaDialect` value may be set within the OpenAPI Object. If this default is not set, then the OAS dialect schema id MUST be used for these Schema Objects. The value of `$schema` within a Schema Object always overrides any default. When a Schema Object is referenced from an external resource which is not an OAS document (e.g. a bare JSON Schema resource), then the value of the `$schema` keyword for schemas within that resource MUST follow [JSON Schema rules](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.1.1). ##### Schema Object Examples ###### Primitive Sample ```json { "type": "string", "format": "email" } ``` ```yaml type: string format: email ``` ###### Simple Model ```json { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" }, "age": { "type": "integer", "format": "int32", "minimum": 0 } } } ``` ```yaml type: object required: - name properties: name: type: string address: $ref: '#/components/schemas/Address' age: type: integer format: int32 minimum: 0 ``` ###### Model with Map/Dictionary Properties For a simple string to string mapping: ```json { "type": "object", "additionalProperties": { "type": "string" } } ``` ```yaml type: object additionalProperties: type: string ``` For a string to model mapping: ```json { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ComplexModel" } } ``` ```yaml type: object additionalProperties: $ref: '#/components/schemas/ComplexModel' ``` ###### Model with Example ```json { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" } }, "required": [ "name" ], "example": { "name": "Puma", "id": 1 } } ``` ```yaml type: object properties: id: type: integer format: int64 name: type: string required: - name example: name: Puma id: 1 ``` ###### Models with Composition ```json { "components": { "schemas": { "ErrorModel": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "integer", "minimum": 100, "maximum": 600 } } }, "ExtendedErrorModel": { "allOf": [ { "$ref": "#/components/schemas/ErrorModel" }, { "type": "object", "required": [ "rootCause" ], "properties": { "rootCause": { "type": "string" } } } ] } } } } ``` ```yaml components: schemas: ErrorModel: type: object required: - message - code properties: message: type: string code: type: integer minimum: 100 maximum: 600 ExtendedErrorModel: allOf: - $ref: '#/components/schemas/ErrorModel' - type: object required: - rootCause properties: rootCause: type: string ``` ###### Models with Polymorphism Support ```json { "components": { "schemas": { "Pet": { "type": "object", "discriminator": { "propertyName": "petType" }, "properties": { "name": { "type": "string" }, "petType": { "type": "string" } }, "required": [ "name", "petType" ] }, "Cat": { "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "huntingSkill": { "type": "string", "description": "The measured skill for hunting", "default": "lazy", "enum": [ "clueless", "lazy", "adventurous", "aggressive" ] } }, "required": [ "huntingSkill" ] } ] }, "Dog": { "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", "allOf": [ { "$ref": "#/components/schemas/Pet" }, { "type": "object", "properties": { "packSize": { "type": "integer", "format": "int32", "description": "the size of the pack the dog is from", "default": 0, "minimum": 0 } }, "required": [ "packSize" ] } ] } } } } ``` ```yaml components: schemas: Pet: type: object discriminator: propertyName: petType properties: name: type: string petType: type: string required: - name - petType Cat: ## "Cat" will be used as the discriminator value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' - type: object properties: huntingSkill: type: string description: The measured skill for hunting enum: - clueless - lazy - adventurous - aggressive required: - huntingSkill Dog: ## "Dog" will be used as the discriminator value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' - type: object properties: packSize: type: integer format: int32 description: the size of the pack the dog is from default: 0 minimum: 0 required: - packSize ``` #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. When using the discriminator, _inline_ schemas will not be considered. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. This object MAY be extended with [Specification Extensions](#specificationExtensions). The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' ``` which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: petType ``` The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: ```json { "id": 12345, "petType": "Cat" } ``` Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ```yaml MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. For example: ```yaml components: schemas: Pet: type: object required: - petType properties: petType: type: string discriminator: propertyName: petType mapping: dog: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean ``` a payload like this: ```json { "petType": "Cat", "name": "misty" } ``` will indicate that the `Cat` schema be used. Likewise this schema: ```json { "petType": "dog", "bark": "soft" } ``` will map to `Dog` because of the definition in the `mapping` element. #### XML Object A metadata object that allows for more fine-tuned XML model definitions. When using arrays, XML element names are *not* inferred (for singular/plural forms) and the `name` property SHOULD be used to add that information. See examples for expected behavior. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. namespace | `string` | The URI of the namespace definition. This MUST be in the form of an absolute URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### XML Object Examples The 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. ###### No XML Element Basic string property: ```json { "animals": { "type": "string" } } ``` ```yaml animals: type: string ``` ```xml ... ``` Basic string array property ([`wrapped`](#xmlWrapped) is `false` by default): ```json { "animals": { "type": "array", "items": { "type": "string" } } } ``` ```yaml animals: type: array items: type: string ``` ```xml ... ... ... ``` ###### XML Name Replacement ```json { "animals": { "type": "string", "xml": { "name": "animal" } } } ``` ```yaml animals: type: string xml: name: animal ``` ```xml ... ``` ###### XML Attribute, Prefix and Namespace In this example, a full model definition is shown. ```json { "Person": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "xml": { "attribute": true } }, "name": { "type": "string", "xml": { "namespace": "https://example.com/schema/sample", "prefix": "sample" } } } } } ``` ```yaml Person: type: object properties: id: type: integer format: int32 xml: attribute: true name: type: string xml: namespace: https://example.com/schema/sample prefix: sample ``` ```xml example ``` ###### XML Arrays Changing the element names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } } } } ``` ```yaml animals: type: array items: type: string xml: name: animal ``` ```xml value value ``` The external `name` property has no effect on the XML: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens" } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens ``` ```xml value value ``` Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: wrapped: true ``` ```xml value value ``` To overcome the naming problem in the example above, the following definition can be used: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: wrapped: true ``` ```xml value value ``` Affecting both internal and external names: ```json { "animals": { "type": "array", "items": { "type": "string", "xml": { "name": "animal" } }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: animal xml: name: aliens wrapped: true ``` ```xml value value ``` If we change the external element but not the internal ones: ```json { "animals": { "type": "array", "items": { "type": "string" }, "xml": { "name": "aliens", "wrapped": true } } } ``` ```yaml animals: type: array items: type: string xml: name: aliens wrapped: true ``` ```xml value value ``` #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). Please note that as of 2020, the implicit flow is about to be deprecated by [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE. ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"mutualTLS"`, `"oauth2"`, `"openIdConnect"`. description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. The OpenID Connect standard requires the use of TLS. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Security Scheme Object Example ###### Basic Authentication Sample ```json { "type": "http", "scheme": "basic" } ``` ```yaml type: http scheme: basic ``` ###### API Key Sample ```json { "type": "apiKey", "name": "api_key", "in": "header" } ``` ```yaml type: apiKey name: api_key in: header ``` ###### JWT Bearer Sample ```json { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", } ``` ```yaml type: http scheme: bearer bearerFormat: JWT ``` ###### Implicit OAuth2 Sample ```json { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### OAuth Flows Object Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0. This object MAY be extended with [Specification Extensions](#specificationExtensions). #### OAuth Flow Object Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples ```JSON { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } } } ``` ```yaml type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets ``` #### Security Requirement Object Lists the required security schemes to execute this operation. The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- {name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. ##### Security Requirement Object Examples ###### Non-OAuth2 Security Requirement ```json { "api_key": [] } ``` ```yaml api_key: [] ``` ###### OAuth2 Security Requirement ```json { "petstore_auth": [ "write:pets", "read:pets" ] } ``` ```yaml petstore_auth: - write:pets - read:pets ``` ###### Optional OAuth2 Security Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object: ```json { "security": [ {}, { "petstore_auth": [ "write:pets", "read:pets" ] } ] } ``` ```yaml security: - {} - petstore_auth: - write:pets - read:pets ``` ### Specification Extensions While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value can be `null`, a primitive, an array or an object. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ### Security Filtering Some objects in the OpenAPI Specification MAY be declared and remain empty, or be completely removed, even though they are inherently the core of the API documentation. The reasoning is to allow an additional layer of access control over the documentation. While not part of the specification itself, certain libraries MAY choose to allow access to parts of the documentation based on some form of authentication/authorization. Two examples of this: 1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification 3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification 2.0 | 2015-12-31 | Donation of Swagger 2.0 to the OpenAPI Initiative 2.0 | 2014-09-08 | Release of Swagger 2.0 1.2 | 2014-03-14 | Initial release of the formal document. 1.1 | 2012-08-22 | Release of Swagger 1.1 1.0 | 2011-08-10 | First release of the Swagger Specification