From d5307aff5debf8fc895208235cc90976d67e7f3a Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Thu, 2 May 2019 14:11:45 +0300 Subject: [PATCH 01/90] Fix broken YAML in examples/v3.0/api-with-examples.yaml --- examples/v3.0/api-with-examples.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 09003b6aba..0e75ef5243 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -40,7 +40,7 @@ paths: ] } ] - } + } '300': description: |- 300 response From 4a8bae90df507334b2a1c6bfe5906f204640f9ff Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Fri, 3 May 2019 08:22:07 +0300 Subject: [PATCH 02/90] Fix additional broken YAML in examples/v3.0/api-with-examples.yaml --- examples/v3.0/api-with-examples.yaml | 51 +++++++++++++++------------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/examples/v3.0/api-with-examples.yaml b/examples/v3.0/api-with-examples.yaml index 0e75ef5243..18726a5476 100644 --- a/examples/v3.0/api-with-examples.yaml +++ b/examples/v3.0/api-with-examples.yaml @@ -15,8 +15,9 @@ paths: application/json: examples: foo: - value: { - "versions": [ + value: + { + "versions": [ { "status": "CURRENT", "updated": "2011-01-21T11:33:21Z", @@ -39,8 +40,8 @@ paths: } ] } - ] - } + ] + } '300': description: |- 300 response @@ -87,11 +88,12 @@ paths: application/json: examples: foo: - value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ + value: + { + "version": { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" @@ -100,9 +102,9 @@ paths: "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } - ], - "id": "v2.0", - "links": [ + ], + "id": "v2.0", + "links": [ { "href": "http://127.0.0.1:8774/v2/", "rel": "self" @@ -122,9 +124,9 @@ paths: "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } - ] + ] + } } - } '203': description: |- 203 response @@ -132,11 +134,12 @@ paths: application/json: examples: foo: - value: { - "version": { - "status": "CURRENT", - "updated": "2011-01-21T11:33:21Z", - "media-types": [ + value: + { + "version": { + "status": "CURRENT", + "updated": "2011-01-21T11:33:21Z", + "media-types": [ { "base": "application/xml", "type": "application/vnd.openstack.compute+xml;version=2" @@ -145,9 +148,9 @@ paths: "base": "application/json", "type": "application/vnd.openstack.compute+json;version=2" } - ], - "id": "v2.0", - "links": [ + ], + "id": "v2.0", + "links": [ { "href": "http://23.253.228.211:8774/v2/", "rel": "self" @@ -162,6 +165,6 @@ paths: "type": "application/vnd.sun.wadl+xml", "rel": "describedby" } - ] + ] + } } - } From 9218ce60424b03794411a8c6d0454c1c6d31aba0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jostein=20Kj=C3=B8nigsen?= Date: Fri, 21 Feb 2020 15:43:51 +0100 Subject: [PATCH 03/90] Remove duplicated paragraph in README.md (#2150) --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 1ea32a2a7f..36aff21c54 100644 --- a/README.md +++ b/README.md @@ -22,10 +22,6 @@ The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3 [3.1.0](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev) - The next MINOR version. Non-breaking changes should be submitted against this branch. -### Future Versions - -[3.1.0](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev) - The next MINOR version. Non-breaking changes should be submitted against this branch. - ### Previous Versions This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications. From 76f184b5e7aa8bce1b1d2d3600a2649b4619af54 Mon Sep 17 00:00:00 2001 From: Alasdair Hurst Date: Tue, 25 Feb 2020 15:08:31 +0000 Subject: [PATCH 04/90] #2157: Update schema to validate refs in headers of encoding objects --- schemas/v3.0/schema.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/schemas/v3.0/schema.yaml b/schemas/v3.0/schema.yaml index 13e47ff08d..b19f0a9669 100644 --- a/schemas/v3.0/schema.yaml +++ b/schemas/v3.0/schema.yaml @@ -1,4 +1,4 @@ -id: https://spec.openapis.org/oas/3.0/schema/2019-04-02 +id: https://spec.openapis.org/oas/3.0/schema/2020-02-25 $schema: http://json-schema.org/draft-04/schema# description: Validation schema for OpenAPI Specification 3.0.X. type: object @@ -987,7 +987,9 @@ definitions: headers: type: object additionalProperties: - $ref: '#/definitions/Header' + oneOf: + - $ref: '#/definitions/Header' + - $ref: '#/definitions/Reference' style: type: string enum: From e42b09013b1ec4093144fde05afe14ff8b4b0c48 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Wed, 26 Feb 2020 15:33:11 +0000 Subject: [PATCH 05/90] Update README.md to discourage +1 comments on issues (#2134) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 36aff21c54..60bc66ae66 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ The OpenAPI Initiative encourages participation from individuals and companies a * Review the [current specification](versions/3.0.3.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 adding a comment to the existing issue or PR. +* 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. From 52f4e1a04831f97d35bbcd438c9a7cec72823660 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 18 Jun 2020 17:20:55 +0100 Subject: [PATCH 06/90] actions: convert-examples-to-json (js version) (#2199) --- .../workflows/convert-examples-to-json.yaml | 50 +++++++++++++++++++ .gitignore | 1 + package.json | 5 +- scripts/yaml2json/yaml2json.js | 30 +++++++++++ 4 files changed, 85 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/convert-examples-to-json.yaml create mode 100755 scripts/yaml2json/yaml2json.js diff --git a/.github/workflows/convert-examples-to-json.yaml b/.github/workflows/convert-examples-to-json.yaml new file mode 100644 index 0000000000..2ed4ca865e --- /dev/null +++ b/.github/workflows/convert-examples-to-json.yaml @@ -0,0 +1,50 @@ +name: 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. + diff --git a/.gitignore b/.gitignore index 88e134ab28..aa8e47b4c6 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ target atlassian-ide-plugin.xml node_modules/ +package-lock.json Gemfile.lock diff --git a/package.json b/package.json index 4a08fdf38c..01be1c8d5c 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,10 @@ "schemas/*" ], "dependencies": {}, - "devDependencies": {}, + "devDependencies": { + "mdv": "^1.0.7", + "yaml": "^1.8.3" + }, "keywords": [ "OpenAPI", "OAS", diff --git a/scripts/yaml2json/yaml2json.js b/scripts/yaml2json/yaml2json.js new file mode 100755 index 0000000000..f69145ad36 --- /dev/null +++ b/scripts/yaml2json/yaml2json.js @@ -0,0 +1,30 @@ +#!/usr/bin/env node + +'use strict'; + +const fs = require('fs'); +const yaml = require('yaml'); + +function convert(filename) { + console.log(filename); + const s = fs.readFileSync(filename,'utf8'); + let obj; + try { + obj = yaml.parse(s, {prettyErrors: true}); + fs.writeFileSync(filename.replace('.yaml','.json'),JSON.stringify(obj,null,2),'utf8'); + } + catch (ex) { + console.warn(' ',ex.message); + process.exitCode = 1; + } +} + +if (process.argv.length<3) { + console.warn('Usage: yaml2json {infiles}'); +} +else { + for (let i=2;i Date: Thu, 18 Jun 2020 17:41:21 -0600 Subject: [PATCH 07/90] v3.1.0-rc0 Release (#2251) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 3.1.0 prep * Update README * Allow specification extensions in discriminator object * Note that specification extensions beginning x-oas- are reserved * security; add mutualTLS securityScheme type * 832 add info.summary (#1779) * Fix: #832. Add info.summary. * Fix: summary is shord, description is verbose. Be consistent with other definitions of summary and description. * fix OIDC url and OAuth2 requirements Signed-off-by: Axel Nennker * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#2018) * Update versions/3.1.0.md Co-Authored-By: Ron * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #2048 and signpost webhooks * Add an example of webhooks * Relocate and expand on webhooks section following feedback * Better wording to describe expectations on API consumers * Clearer wording for why the paths element is here * Update language to make callbacks clearer * Align the OAS 3.1 nullable language with the 3.0.3 (#2115) This adapts the language from PR #2046, with minimal wording tweaks to account for type now being able to have multiple values (type arrays). * allow, but discourage, requestBody for GET, HEAD, DELETE (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107) * Checkpoint of draft * Fix typo. Co-Authored-By: Darrel * Fix plural anchor Co-Authored-By: Mike Ralphson * Remove superfluous specification Co-Authored-By: Phil Sturgeon Co-authored-by: Darrel Co-authored-by: Mike Ralphson Co-authored-by: Phil Sturgeon * Fix table cell formatting containing `nullable` description (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#1781) * Make paths object optional * Adding reusable Path Item Objects Under `components` * Adopt DM's suggested change to OpenAPI doc definition * Cleanup use of specification and definition where we mean document * multipartite>composite, define ACL * Add ' | Reference Object' to callbacks/webhooks Co-authored-by: Ron * Fwd port v3.0.3 dev to v3.1.0 dev (#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson * retain typo in v3.0.2; fix for v3.0.3 (#1899) Signed-off-by: Mike Ralphson * Clarify empty Security Requirement Object usage and validity (#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron Signed-off-by: Mike Ralphson * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson * ted updates Signed-off-by: Mike Ralphson * Replace 'application' by 'API' within the 'Info Object' definition. (#2004) Signed-off-by: Mike Ralphson * Path Templating Clarification - proposed fix for #1830. (#1831) * Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. Signed-off-by: Mike Ralphson * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson * Updated text for OperationRef Signed-off-by: Mike Ralphson * fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson * Explain unclear semantics of property `$ref` in Path Item Object (#1964) * Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in https://github.com/OAI/OpenAPI-Specification/issues/1038#issuecomment-295594246 the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.1.0.md Co-authored-by: Ron Signed-off-by: Mike Ralphson * Clarify constraints on Security Scheme Object Scheme Property (#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme Signed-off-by: Mike Ralphson * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson * Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson * Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Signed-off-by: Mike Ralphson * Update versions/3.1.0.md Co-Authored-By: Darrel Signed-off-by: Mike Ralphson * Fixed typo Signed-off-by: Mike Ralphson * explicit 'forward slash' Signed-off-by: Mike Ralphson * fix #2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson * OpenAPI not Open API Signed-off-by: Mike Ralphson * backticks Signed-off-by: Mike Ralphson * minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson Co-authored-by: Ron Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson * Removed confusing comment Signed-off-by: Mike Ralphson * Clarify the spec to allow optional or unspecified OAuth scopes (#1888) * Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron Signed-off-by: Mike Ralphson * The examples keyword is not supported inside schema (#2042) * examples not supported inside schema * figured it out * a tiny little edit Signed-off-by: Mike Ralphson * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Ron Co-authored-by: Phil Sturgeon Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Darrel Miller Co-authored-by: Carsten Brandt Co-authored-by: Henry Andrews Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde * security; widen use of scopes array to other securityScheme types (#1829) Co-authored-by: Ron * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#1946) Co-authored-by: Phil Sturgeon * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (#2226) This brings exclusiveMinimum, exclusiveMaximum, minimum, and maximum, into full modern JSON Schema compatibility. There are no edits directly mentioning minimum and maximum, but removing the boolean form simplifies their processing by making it context-independent. * Update "format" and "content*" for new JSON Schema (#2200) * Update "format" and "content*" for new JSON Schema This removes OAS formats and examples that are now superfluous as they are part of the 2019-09 JSON Schema draft. Similarly it deprecates the "byte" and "binary" formats in favor of JSON Schema's "contentEncoding" and "contentMediaType" keywords, and updates various related exapmles and other guidance. It also removes confusingly blank rows in the OAS format table. * "format" is an annotation * Fix broken table, type, in Encoding Object Broke some things while updating for "content*" * Fix format of `format` Backticks, not double quotes. * Remove unneeded detail on "format" This was just duplicating info from the JSON Schema spec. Co-authored-by: Darrel * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel * [3.1.0-dev] drop OAS semver requirement (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel * Remove "nullable" entirely (#2246) * Update version for release (#2269) Co-authored-by: Mike Ralphson Co-authored-by: Roberto Polli Co-authored-by: Axel Nennker Co-authored-by: Phil Sturgeon Co-authored-by: Mike Kistler Co-authored-by: Darrel Co-authored-by: Arhimenrius Co-authored-by: Lorna Jane Mitchell Co-authored-by: Henry Andrews Co-authored-by: Alan Crosswell Co-authored-by: Helen Kosova Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Carsten Brandt Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde Co-authored-by: Marsh Gardiner Co-authored-by: Phil Sturgeon --- README.md | 10 +- examples/v3.1/webhook-example.yaml | 61 + versions/3.1.0.md | 3434 ++++++++++++++++++++++++++++ 3 files changed, 3502 insertions(+), 3 deletions(-) create mode 100644 examples/v3.1/webhook-example.yaml create mode 100644 versions/3.1.0.md diff --git a/README.md b/README.md index 60bc66ae66..0bd81d371f 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,17 @@ ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) + +**This is the WIP branch for the next minor version of the spec - 3.1.0. Non-breaking changes should be submitted against this branch, specifically against [3.1.0.md](https://github.com/OAI/OpenAPI-Specification/blob/v3.1.0-dev/versions/3.1.0.md).** + + 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 [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer), 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. +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 API's 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. +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 REST APIs. 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 REST API. +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. diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml new file mode 100644 index 0000000000..664966a35a --- /dev/null +++ b/examples/v3.1/webhook-example.yaml @@ -0,0 +1,61 @@ +openapi: 3.1.0 +info: + title: Webhook Example + version: 1.0.0 +paths: + # OpenAPI documents all need a paths element + /pets: + get: + summary: List all pets + operationId: listPets + 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 + content: + application/json: + schema: + $ref: "#/components/schemas/Pets" + +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 + Pets: + type: array + items: + $ref: "#/components/schemas/Pet" + + diff --git a/versions/3.1.0.md b/versions/3.1.0.md new file mode 100644 index 0000000000..fc282f3777 --- /dev/null +++ b/versions/3.1.0.md @@ -0,0 +1,3434 @@ +# OpenAPI Specification + +#### Version 3.1.0-rc0 + +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](#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 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). + +##### 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 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 Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.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. +Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09. + +Primitives have an optional modifier property: `format`, which is defined by JSON Schema. +OAS uses several known additional 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. +Additional formats MAY be used even though undefined by either JSON Schema or 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. + +Note that by default, JSON Schema validators will not attempt to validate the `format` keyword. https://json-schema.org/draft/2019-09/release-notes.html#format-vocabulary + +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 are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. This includes relative references in [`Reference Objects`](#referenceObject), outside of any [`Schema Object`](#schemaObject). + +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 2019-09](https://json-schema.org/draft/2019-09/json-schema-core.html). If no parent schema contains an `$id`, then the Base URI is determined as in the previous paragraph. + +### 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. +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 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", + "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. 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": "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. MUST be in the format 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 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) | 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 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 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) | **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) | 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`](#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": "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 text plain format + 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", + "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, such schemas use the `contentEncoding` JSON Schema keyword rather than the `format` keyword. This 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). + +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) SHOULD omit `schema`, as no JSON Schema type is suitable: + +```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 + contentEncoding: base64 +``` + +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: + contentMediaType: 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 [RFC 7578](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` +* If the JSON Schema keyword `contentMediaType` is used and no Encoding Object is present, then the Content-Type is that which is specified by `contentMediaType`, however if an Encoding Object is present, then `contentMediaType` SHALL be ignored + +As with non-multipart request or response bodies, when using `contentMediaType` to specify a binary Content-Type without also using `contentEncoding`, the JSON Schema `type` keyword is omitted. + +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 with contentMediaType is the contentMediaType (image/png here) + contentMediaType: image/png + 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: when `type` is absent and `contentMediaType` is present - the value of `contentMediaType`; when both `type` and `contentMediaType` are absent - `application/octet-stream`; for `string` with a `contentEncoding` - `application/octet-string`; 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` 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/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: + type: string + contentMediaType: image/jpeg + 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. 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. + +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 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: '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. +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 [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 OpenAPI document, internally and externally. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +$ref | `string` | **REQUIRED**. The reference string. +summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not define 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 define 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 2019-09](http://json-schema.org/). + +For more information about the properties, see [JSON Schema Core](https://json-schema.org/draft/2019-09/json-schema-core.html) and [JSON Schema Validation](https://json-schema.org/draft/2019-09/json-schema-validation.html). + +Unless stated otherwise, the property definitions follow the JSON Schema. + +##### Properties + +The OpenAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way. + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification. + +- 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. + +In addition to the JSON Schema properties defined in the vocabularies defined in the JSON Schema Core and JSON Schema Validation specifications, any properties can be used from any vocabularies, or entirely arbitrary keywords. The OpenAPI Specification defines an additional vocabulary of keywords which MAY be used along with the JSON Schema vocabulary keywords for further schema description: + +##### 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). + +###### 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 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 `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": "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 currently (2019) the implicit flow is about to be deprecated [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/id/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 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. 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-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. 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 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-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 From 55f80d11c22009a7e891b108ed87250d8fdc1862 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 Jun 2020 17:42:23 -0600 Subject: [PATCH 08/90] Update README.md (#2253) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0bd81d371f..d52d20ff0d 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,9 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md). -### Future Versions +## Current Release Candidate Version - 3.1.0-RC0 -[3.1.0](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev) - The next MINOR version. Non-breaking changes should be submitted against this branch. +We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC0](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). ### Previous Versions From 53c50e159d2ac4e545a029a598a86f747ffe2d33 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 18 Jun 2020 17:54:07 -0600 Subject: [PATCH 09/90] Fixing oopsie (#2270) --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index d52d20ff0d..b2395ebf73 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,6 @@ ![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200) -**This is the WIP branch for the next minor version of the spec - 3.1.0. Non-breaking changes should be submitted against this branch, specifically against [3.1.0.md](https://github.com/OAI/OpenAPI-Specification/blob/v3.1.0-dev/versions/3.1.0.md).** - - 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. From 97ec145130e216fa8e59efc228c9211f439b202c Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 2 Jul 2020 17:13:37 +0100 Subject: [PATCH 10/90] Update build badge in README.md (#2271) This replaces the old Travis CI build badge with a GitHub Actions one. Signed-off-by: Mike Ralphson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b2395ebf73..fec337e71a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # The OpenAPI Specification -[![Build Status](https://travis-ci.org/OAI/OpenAPI-Specification.svg?branch=master)](https://travis-ci.org/OAI/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) From 97ec9ebe2b39bb28ecf799f6a34772d307975d6d Mon Sep 17 00:00:00 2001 From: Phil Barila <62034965+philb-lr@users.noreply.github.com> Date: Thu, 2 Jul 2020 10:14:12 -0600 Subject: [PATCH 11/90] Update uspto.yaml (#2221) Lucense -> Lucene --- examples/v3.0/uspto.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/v3.0/uspto.yaml b/examples/v3.0/uspto.yaml index 8e9b159f52..d3011520d0 100644 --- a/examples/v3.0/uspto.yaml +++ b/examples/v3.0/uspto.yaml @@ -115,7 +115,7 @@ paths: Provides search capability for the data set with the given search criteria. description: >- - This API is based on Solr/Lucense Search. The data is indexed using + 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 From d1cc440056f1c7bb913bcd643b15c14ee1c409f4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 2 Jul 2020 12:17:16 -0400 Subject: [PATCH 12/90] Update JSON example files (#2268) * Update JSON example files * Update JSON example files * Update JSON example files Co-authored-by: Mike Ralphson Co-authored-by: Ron Co-authored-by: Phil Barila <62034965+philb-lr@users.noreply.github.com> --- examples/v3.0/api-with-examples.json | 167 ++++++++++++++ examples/v3.0/callback-example.json | 84 +++++++ examples/v3.0/link-example.json | 323 +++++++++++++++++++++++++++ examples/v3.0/petstore-expanded.json | 242 ++++++++++++++++++++ examples/v3.0/petstore.json | 177 +++++++++++++++ examples/v3.0/uspto.json | 252 +++++++++++++++++++++ examples/v3.1/webhook-example.json | 88 ++++++++ 7 files changed, 1333 insertions(+) create mode 100644 examples/v3.0/api-with-examples.json create mode 100644 examples/v3.0/callback-example.json create mode 100644 examples/v3.0/link-example.json create mode 100644 examples/v3.0/petstore-expanded.json create mode 100644 examples/v3.0/petstore.json create mode 100644 examples/v3.0/uspto.json create mode 100644 examples/v3.1/webhook-example.json diff --git a/examples/v3.0/api-with-examples.json b/examples/v3.0/api-with-examples.json new file mode 100644 index 0000000000..0fd2077b3e --- /dev/null +++ b/examples/v3.0/api-with-examples.json @@ -0,0 +1,167 @@ +{ + "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" + } + ] + } + } + } + } + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.0/callback-example.json b/examples/v3.0/callback-example.json new file mode 100644 index 0000000000..9a4df39b45 --- /dev/null +++ b/examples/v3.0/callback-example.json @@ -0,0 +1,84 @@ +{ + "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" + } + } + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.0/link-example.json b/examples/v3.0/link-example.json new file mode 100644 index 0000000000..bc98e635f1 --- /dev/null +++ b/examples/v3.0/link-example.json @@ -0,0 +1,323 @@ +{ + "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" + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.0/petstore-expanded.json b/examples/v3.0/petstore-expanded.json new file mode 100644 index 0000000000..9bd527fa38 --- /dev/null +++ b/examples/v3.0/petstore-expanded.json @@ -0,0 +1,242 @@ +{ + "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" + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.0/petstore.json b/examples/v3.0/petstore.json new file mode 100644 index 0000000000..583b1e0990 --- /dev/null +++ b/examples/v3.0/petstore.json @@ -0,0 +1,177 @@ +{ + "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" + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.0/uspto.json b/examples/v3.0/uspto.json new file mode 100644 index 0000000000..cd32f64c5f --- /dev/null +++ b/examples/v3.0/uspto.json @@ -0,0 +1,252 @@ +{ + "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" + } + } + } + } + } + } + } + } +} \ No newline at end of file diff --git a/examples/v3.1/webhook-example.json b/examples/v3.1/webhook-example.json new file mode 100644 index 0000000000..4af0289112 --- /dev/null +++ b/examples/v3.1/webhook-example.json @@ -0,0 +1,88 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Webhook Example", + "version": "1.0.0" + }, + "paths": { + "/pets": { + "get": { + "summary": "List all pets", + "operationId": "listPets", + "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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Pets" + } + } + } + } + } + } + } + }, + "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" + } + } + }, + "Pets": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pet" + } + } + } + } +} \ No newline at end of file From 5285c690a1401a3d330fc4d3a862e0cb0134c57e Mon Sep 17 00:00:00 2001 From: Neal Caidin Date: Mon, 20 Jul 2020 10:26:50 -0400 Subject: [PATCH 13/90] Update TOB.md (#2291) Darrel, Jerome, and Jeremy have been re-elected for another 2 year term. Updating the BGB elected term. --- TOB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOB.md b/TOB.md index bf715ef79a..0a6f6f2868 100644 --- a/TOB.md +++ b/TOB.md @@ -12,7 +12,7 @@ Marsh Gardiner @earth2marsh Ron Ratovsky @webron -## BGB Elected - terms through May 2020 +## BGB Elected - terms through May 2022 Darrel Miller @darrelmiller From f8449d1a893cc6a811c6f3d87e88b05761dc5397 Mon Sep 17 00:00:00 2001 From: Ron Date: Thu, 8 Oct 2020 19:30:29 -0600 Subject: [PATCH 14/90] v3.1.0-rc1 Release (#2370) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 3.1.0 prep * Update README * Allow specification extensions in discriminator object * Note that specification extensions beginning x-oas- are reserved * security; add mutualTLS securityScheme type * 832 add info.summary (#1779) * Fix: #832. Add info.summary. * Fix: summary is shord, description is verbose. Be consistent with other definitions of summary and description. * fix OIDC url and OAuth2 requirements Signed-off-by: Axel Nennker * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#2018) * Update versions/3.1.0.md Co-Authored-By: Ron * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #2048 and signpost webhooks * Add an example of webhooks * Relocate and expand on webhooks section following feedback * Better wording to describe expectations on API consumers * Clearer wording for why the paths element is here * Update language to make callbacks clearer * Align the OAS 3.1 nullable language with the 3.0.3 (#2115) This adapts the language from PR #2046, with minimal wording tweaks to account for type now being able to have multiple values (type arrays). * allow, but discourage, requestBody for GET, HEAD, DELETE (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107) * Checkpoint of draft * Fix typo. Co-Authored-By: Darrel * Fix plural anchor Co-Authored-By: Mike Ralphson * Remove superfluous specification Co-Authored-By: Phil Sturgeon Co-authored-by: Darrel Co-authored-by: Mike Ralphson Co-authored-by: Phil Sturgeon * Fix table cell formatting containing `nullable` description (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#1781) * Make paths object optional * Adding reusable Path Item Objects Under `components` * Adopt DM's suggested change to OpenAPI doc definition * Cleanup use of specification and definition where we mean document * multipartite>composite, define ACL * Add ' | Reference Object' to callbacks/webhooks Co-authored-by: Ron * Fwd port v3.0.3 dev to v3.1.0 dev (#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson * retain typo in v3.0.2; fix for v3.0.3 (#1899) Signed-off-by: Mike Ralphson * Clarify empty Security Requirement Object usage and validity (#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron Signed-off-by: Mike Ralphson * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson * ted updates Signed-off-by: Mike Ralphson * Replace 'application' by 'API' within the 'Info Object' definition. (#2004) Signed-off-by: Mike Ralphson * Path Templating Clarification - proposed fix for #1830. (#1831) * Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. Signed-off-by: Mike Ralphson * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson * Updated text for OperationRef Signed-off-by: Mike Ralphson * fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson * Explain unclear semantics of property `$ref` in Path Item Object (#1964) * Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in https://github.com/OAI/OpenAPI-Specification/issues/1038#issuecomment-295594246 the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.1.0.md Co-authored-by: Ron Signed-off-by: Mike Ralphson * Clarify constraints on Security Scheme Object Scheme Property (#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme Signed-off-by: Mike Ralphson * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson * Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson * Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Signed-off-by: Mike Ralphson * Update versions/3.1.0.md Co-Authored-By: Darrel Signed-off-by: Mike Ralphson * Fixed typo Signed-off-by: Mike Ralphson * explicit 'forward slash' Signed-off-by: Mike Ralphson * fix #2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson * OpenAPI not Open API Signed-off-by: Mike Ralphson * backticks Signed-off-by: Mike Ralphson * minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson Co-authored-by: Ron Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson * Removed confusing comment Signed-off-by: Mike Ralphson * Clarify the spec to allow optional or unspecified OAuth scopes (#1888) * Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron Signed-off-by: Mike Ralphson * The examples keyword is not supported inside schema (#2042) * examples not supported inside schema * figured it out * a tiny little edit Signed-off-by: Mike Ralphson * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Ron Co-authored-by: Phil Sturgeon Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Darrel Miller Co-authored-by: Carsten Brandt Co-authored-by: Henry Andrews Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde * security; widen use of scopes array to other securityScheme types (#1829) Co-authored-by: Ron * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#1946) Co-authored-by: Phil Sturgeon * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (#2226) This brings exclusiveMinimum, exclusiveMaximum, minimum, and maximum, into full modern JSON Schema compatibility. There are no edits directly mentioning minimum and maximum, but removing the boolean form simplifies their processing by making it context-independent. * Update "format" and "content*" for new JSON Schema (#2200) * Update "format" and "content*" for new JSON Schema This removes OAS formats and examples that are now superfluous as they are part of the 2019-09 JSON Schema draft. Similarly it deprecates the "byte" and "binary" formats in favor of JSON Schema's "contentEncoding" and "contentMediaType" keywords, and updates various related exapmles and other guidance. It also removes confusingly blank rows in the OAS format table. * "format" is an annotation * Fix broken table, type, in Encoding Object Broke some things while updating for "content*" * Fix format of `format` Backticks, not double quotes. * Remove unneeded detail on "format" This was just duplicating info from the JSON Schema spec. Co-authored-by: Darrel * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel * [3.1.0-dev] drop OAS semver requirement (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel * Remove "nullable" entirely (#2246) * Update version for release (#2269) * $schema Guidance (#2266) * chore: explain how $schema might work * reordered and made it specifically only schema resources * Update versions/3.1.0.md Co-authored-by: Karen Etheridge * Update versions/3.1.0.md Co-authored-by: Ben Hutton * new approach Co-authored-by: Phil Sturgeon Co-authored-by: Karen Etheridge Co-authored-by: Ben Hutton * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (#2302) * The JSON schema specification states the format keyword can be used for any data type, not just primitive types * The JSON schema specification states the format keyword can be used for any data type, not just primitive types * Added change to address #2287 (#2328) Co-authored-by: Darrel Miller * Make Server Variable Object's properties more strict (#2335) Followup to #1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (#2329) Co-authored-by: Darrel Miller * 3.1.0-rc1 Release prep (#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev Co-authored-by: Mike Ralphson Co-authored-by: Roberto Polli Co-authored-by: Axel Nennker Co-authored-by: Phil Sturgeon Co-authored-by: Mike Kistler Co-authored-by: Darrel Co-authored-by: Arhimenrius Co-authored-by: Lorna Jane Mitchell Co-authored-by: Henry Andrews Co-authored-by: Alan Crosswell Co-authored-by: Helen Kosova Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Carsten Brandt Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde Co-authored-by: Marsh Gardiner Co-authored-by: Phil Sturgeon Co-authored-by: Karen Etheridge Co-authored-by: Ben Hutton Co-authored-by: Sebastien Rosset Co-authored-by: Darrel Miller Co-authored-by: Vladimir Gorej Co-authored-by: Helen Kosova --- README.md | 4 ++-- versions/3.1.0.md | 34 +++++++++++++++++++--------------- 2 files changed, 21 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index fec337e71a..e8f9f8e39b 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md). -## Current Release Candidate Version - 3.1.0-RC0 +## Current Release Candidate Version - 3.1.0-RC1 -We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC0](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). +We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC1](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). ### Previous Versions diff --git a/versions/3.1.0.md b/versions/3.1.0.md index fc282f3777..16fd23689e 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1,6 +1,6 @@ # OpenAPI Specification -#### Version 3.1.0-rc0 +#### Version 3.1.0-rc1 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. @@ -73,7 +73,7 @@ A self-contained or composite resource which defines or describes an API or elem ##### 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). +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. ##### Media Types Media type definitions are spread across several resources. @@ -139,17 +139,12 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2). +Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.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. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09. -Primitives have an optional modifier property: `format`, which is defined by JSON Schema. -OAS uses several known additional 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. -Additional formats MAY be used even though undefined by either JSON Schema or 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. - -Note that by default, JSON Schema validators will not attempt to validate the `format` keyword. https://json-schema.org/draft/2019-09/release-notes.html#format-vocabulary +As defined by JSON Schema, 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: @@ -429,8 +424,8 @@ An object representing a Server Variable for server URL template substitution. 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. +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). @@ -445,7 +440,7 @@ All objects defined within the components object will have no effect on the API Field Name | Type | Description ---|:---|--- - schemas | Map[`string`, [Schema Object](#schemaObject) | An object to hold reusable [Schema Objects](#schemaObject). + 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). @@ -850,7 +845,7 @@ Field Name | Type | Description 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) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. +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. @@ -1485,7 +1480,7 @@ In addition, specific media types MAY be specified: # multiple, specific media types may be specified: requestBody: content: - # a binary file of type png or jpeg + # a binary file of type png or jpeg image/jpeg: {} image/png: {} ``` @@ -2336,6 +2331,14 @@ As such, inline schema definitions, which do not have a given id, *cannot* be us 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. +###### Picking Schema Vocabularies + +It is important for tooling to be able to detect what meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema Object, or some custom meta schema. + +`$schema` MAY be present in any Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. + +When `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. + ##### Schema Object Examples ###### Primitive Sample @@ -3419,6 +3422,7 @@ Two examples of this: Version | Date | Notes --- | --- | --- +3.1.0-rc0 | 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 From 2e10c7a4e66b2518da00747d4f7c212464aacf10 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 3 Dec 2020 17:09:15 +0000 Subject: [PATCH 15/90] Add adopted CODE_OF_CONDUCT.md (#2416) --- CODE_OF_CONDUCT.md | 118 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..37a9b6e40e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,118 @@ +Code 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/). From e32baaa4c8f987b5c447208c70ae96c39600ebe7 Mon Sep 17 00:00:00 2001 From: Darrel Date: Thu, 14 Jan 2021 12:15:28 -0500 Subject: [PATCH 16/90] Added wording to clarify scope of references (#2435) * Added wording to clarify scope of references * Added wording based on conversations in OAI TSC Meeting * Update versions/3.1.0.md --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 16fd23689e..11a7abfc25 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2235,7 +2235,7 @@ description: Pets operations #### Reference Object -A simple object to allow referencing other components in the OpenAPI document, internally and externally. +A simple object to allow referencing other objects in the OpenAPI document, internally and externally. Targets of a reference do not need to be contained in a components section and for external references, targets MAY exist within any compatible resource. Targets are subject to the same constraints as inline objects. ##### Fixed Fields Field Name | Type | Description From f1adc846131b33be72df6a0c87e5e5da59dde0ff Mon Sep 17 00:00:00 2001 From: Christian Franchin Date: Thu, 11 Feb 2021 14:32:31 -0300 Subject: [PATCH 17/90] Fixed the webhook example (#2434) Signed-off-by: Christian Franchin dos Santos --- examples/v3.1/webhook-example.json | 38 ------------------------------ examples/v3.1/webhook-example.yaml | 28 +--------------------- 2 files changed, 1 insertion(+), 65 deletions(-) diff --git a/examples/v3.1/webhook-example.json b/examples/v3.1/webhook-example.json index 4af0289112..712a42f120 100644 --- a/examples/v3.1/webhook-example.json +++ b/examples/v3.1/webhook-example.json @@ -4,38 +4,6 @@ "title": "Webhook Example", "version": "1.0.0" }, - "paths": { - "/pets": { - "get": { - "summary": "List all pets", - "operationId": "listPets", - "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", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Pets" - } - } - } - } - } - } - } - }, "webhooks": { "newPet": { "post": { @@ -76,12 +44,6 @@ "type": "string" } } - }, - "Pets": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pet" - } } } } diff --git a/examples/v3.1/webhook-example.yaml b/examples/v3.1/webhook-example.yaml index 664966a35a..2ac1cda985 100644 --- a/examples/v3.1/webhook-example.yaml +++ b/examples/v3.1/webhook-example.yaml @@ -2,28 +2,7 @@ openapi: 3.1.0 info: title: Webhook Example version: 1.0.0 -paths: - # OpenAPI documents all need a paths element - /pets: - get: - summary: List all pets - operationId: listPets - 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 - content: - application/json: - schema: - $ref: "#/components/schemas/Pets" - +# 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: @@ -53,9 +32,4 @@ components: type: string tag: type: string - Pets: - type: array - items: - $ref: "#/components/schemas/Pet" - From 42a9e3d4eddade52363a5c4fac852e80681c2fe5 Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 16 Feb 2021 12:30:29 -0700 Subject: [PATCH 18/90] 3.1.0 Release (#2462) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 3.1.0 prep * Update README * Allow specification extensions in discriminator object * Note that specification extensions beginning x-oas- are reserved * security; add mutualTLS securityScheme type * 832 add info.summary (#1779) * Fix: #832. Add info.summary. * Fix: summary is shord, description is verbose. Be consistent with other definitions of summary and description. * fix OIDC url and OAuth2 requirements Signed-off-by: Axel Nennker * Update Schema Object to proper JSON Schema * update vocab and arbitrary props * another go at arbitrary keywords * feedback from @handrews * Support style, explode, allowReserved encoding for multipart/form-data (#2066) * Extend style, explode, allowReserved in encoding to multipart-formdata (#2018) * Update versions/3.1.0.md Co-Authored-By: Ron * Replace details of multipart/form-data format with referce to RFC 7578 * Update versions/3.1.0.md Co-Authored-By: Darrel * default should match json schema * removed json schema keyworld list, its just all of em. * redundant $ref reference * Correct Styles Values for spaceDelimited and pipeDelimited, as based on Style Examples, they support objects. * Add support for webhooks as a top-level element (#2103) * Add webhooks as a top-level element to the spec * Add the changes from #2048 and signpost webhooks * Add an example of webhooks * Relocate and expand on webhooks section following feedback * Better wording to describe expectations on API consumers * Clearer wording for why the paths element is here * Update language to make callbacks clearer * Align the OAS 3.1 nullable language with the 3.0.3 (#2115) This adapts the language from PR #2046, with minimal wording tweaks to account for type now being able to have multiple values (type arrays). * allow, but discourage, requestBody for GET, HEAD, DELETE (#2117) * Reference Object and Schema Object use of $ref updates for 2019-09 / OAS 3.1 (#2107) * Checkpoint of draft * Fix typo. Co-Authored-By: Darrel * Fix plural anchor Co-Authored-By: Mike Ralphson * Remove superfluous specification Co-Authored-By: Phil Sturgeon Co-authored-by: Darrel Co-authored-by: Mike Ralphson Co-authored-by: Phil Sturgeon * Fix table cell formatting containing `nullable` description (#2152) * Add SPDX identifier field to license object, fixes #1599 (#2105) * Add information about objects to the description too * Make paths object optional (#1781) * Make paths object optional * Adding reusable Path Item Objects Under `components` * Adopt DM's suggested change to OpenAPI doc definition * Cleanup use of specification and definition where we mean document * multipartite>composite, define ACL * Add ' | Reference Object' to callbacks/webhooks Co-authored-by: Ron * Fwd port v3.0.3 dev to v3.1.0 dev (#2163) * fix typo in Callback Object Signed-off-by: Mike Ralphson * retain typo in v3.0.2; fix for v3.0.3 (#1899) Signed-off-by: Mike Ralphson * Clarify empty Security Requirement Object usage and validity (#1886) * Clarify empty Security Requirement Object usage and validity * Reorder sentences to make clearer. * Remove wrong text. * Removed unneeded text. Co-authored-by: Ron Signed-off-by: Mike Ralphson * Ron's wording for Darrels feedback Signed-off-by: Mike Ralphson * ted updates Signed-off-by: Mike Ralphson * Replace 'application' by 'API' within the 'Info Object' definition. (#2004) Signed-off-by: Mike Ralphson * Path Templating Clarification - proposed fix for #1830. (#1831) * Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. * #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. * Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. Signed-off-by: Mike Ralphson * yaml.org supports https, but www.yaml.org is misconfigured Signed-off-by: Mike Ralphson * Updated text for OperationRef Signed-off-by: Mike Ralphson * fix a typo in the Security Filtering section (#1837) * fix a typo in the Security Filtering section * Security filtering slight reword Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Make ABNF for runtime expressions complete Signed-off-by: Mike Ralphson * Explain unclear semantics of property `$ref` in Path Item Object (#1964) * Explain unclear semantics of property `$ref` in Path Item Object Currently, as explained in https://github.com/OAI/OpenAPI-Specification/issues/1038#issuecomment-295594246 the description of `$ref` in [Path Item Object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#pathItemObject) is unclear about the semantics behing it. I took the explaination from issue #1038 to make it more clear. * Update versions/3.1.0.md Co-authored-by: Ron Signed-off-by: Mike Ralphson * Clarify constraints on Security Scheme Object Scheme Property (#1880) * Wording around scheme extensions * Clarified that securitySchemeScheme is only a SHOULD be registered scheme Signed-off-by: Mike Ralphson * fix difference between yaml and json in Response Object Examples Signed-off-by: Mike Ralphson * Server Variable Object clarifications (#1809) * Server Variable Object clarifications * Toned language down for proper semver versioning Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson * Update 3.0.3 for release (#2149) * Update README.md for release * Update release date for 3.0.3 Signed-off-by: Mike Ralphson * Update versions/3.1.0.md Co-Authored-By: Darrel Signed-off-by: Mike Ralphson * Fixed typo Signed-off-by: Mike Ralphson * explicit 'forward slash' Signed-off-by: Mike Ralphson * fix #2053: `style` keyword is not supported inside Schema object Signed-off-by: Mike Ralphson * OpenAPI not Open API Signed-off-by: Mike Ralphson * backticks Signed-off-by: Mike Ralphson * minor clarification for operationId usage in link objects (#1733) * minor clarification it's a bit confusing that both the id and the reference are called "operationId", so this tweak makes the text a bit more explicit. * use right terminology Co-Authored-By: Mike Ralphson Co-authored-by: Ron Co-authored-by: Mike Ralphson Signed-off-by: Mike Ralphson * Update 3.1.0.md fixed typo Signed-off-by: Mike Ralphson * Removed confusing comment Signed-off-by: Mike Ralphson * Clarify the spec to allow optional or unspecified OAuth scopes (#1888) * Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. * Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. * For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. * removed unnecessary example header Co-authored-by: Ron Signed-off-by: Mike Ralphson * The examples keyword is not supported inside schema (#2042) * examples not supported inside schema * figured it out * a tiny little edit Signed-off-by: Mike Ralphson * Fix 'Security Scheme Object' definition with OAuth 2.0 grant types. (#2006) Signed-off-by: Mike Ralphson * Fix formatting errors in example (#2132) Signed-off-by: Mike Ralphson Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Ron Co-authored-by: Phil Sturgeon Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Darrel Miller Co-authored-by: Carsten Brandt Co-authored-by: Henry Andrews Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde * security; widen use of scopes array to other securityScheme types (#1829) Co-authored-by: Ron * Allow summary and description as $ref siblings (#2181) * HTTP not REST (#1946) Co-authored-by: Phil Sturgeon * Missing updates While going over the changes for the release notes, found two issues: - The TOC entry for `Relative references in URIs` was not modified to match the change in the spec. - The `Paths Object` had an extra sentence that should have not been there (referencing sub-documents and overlays). * Remove boolean compatibility for exclusive* (#2226) This brings exclusiveMinimum, exclusiveMaximum, minimum, and maximum, into full modern JSON Schema compatibility. There are no edits directly mentioning minimum and maximum, but removing the boolean form simplifies their processing by making it context-independent. * Update "format" and "content*" for new JSON Schema (#2200) * Update "format" and "content*" for new JSON Schema This removes OAS formats and examples that are now superfluous as they are part of the 2019-09 JSON Schema draft. Similarly it deprecates the "byte" and "binary" formats in favor of JSON Schema's "contentEncoding" and "contentMediaType" keywords, and updates various related exapmles and other guidance. It also removes confusingly blank rows in the OAS format table. * "format" is an annotation * Fix broken table, type, in Encoding Object Broke some things while updating for "content*" * Fix format of `format` Backticks, not double quotes. * Remove unneeded detail on "format" This was just duplicating info from the JSON Schema spec. Co-authored-by: Darrel * Remove "byte" and "binary" formats altogether. Instead of just deprecating. The "content*" keywords now cover these use cases. * Harmonize JSON Schema content* + Media Type Object Includes harmonizing with the Encoding Object. In general, OpenAPI objects set the media type, although there is a case for `contentMediaType` with multipart/form-data. Otherwise, `contentEncoding` replaces the now-removed custom formats. A possibly controversial change is to indicate unencoded binary data by omitting `type` (or omitting the schema altogether), as binary data does not conform to JSON string requirements. This could still be done with `type: string` if that is preferred. It's going to be a bit weird either way. I can add wording in the next JSON Schema draft to clarify whichever approach makes more sense. * Fix typos from review * Remove stray {} * Fix inconsistencies contentMediaType and Encoding Object Co-authored-by: Darrel * [3.1.0-dev] drop OAS semver requirement (#2243) * drop OAS semver requirement * Update versions/3.1.0.md Co-authored-by: Darrel * Remove "nullable" entirely (#2246) * x-oas- to x-oai- (v3.1.0-dev) * Update version for release (#2269) * $schema Guidance (#2266) * chore: explain how $schema might work * reordered and made it specifically only schema resources * Update versions/3.1.0.md Co-authored-by: Karen Etheridge * Update versions/3.1.0.md Co-authored-by: Ben Hutton * new approach Co-authored-by: Phil Sturgeon Co-authored-by: Karen Etheridge Co-authored-by: Ben Hutton * x-oai- / x-oas-; reserve both * v3.1.0: rephrase data-type section because `format` keyword can be used for any data type. (#2302) * The JSON schema specification states the format keyword can be used for any data type, not just primitive types * The JSON schema specification states the format keyword can be used for any data type, not just primitive types * Added change to address #2287 (#2328) Co-authored-by: Darrel Miller * Make Server Variable Object's properties more strict (#2335) Followup to #1809, now that we allow breaking changes. * docs(Components): fix typo in schemas field type (#2337) * Fix indentation of a YAML comment * Removed required constraint on responses object (#2329) Co-authored-by: Darrel Miller * 3.1.0-rc1 Release prep (#2369) * Update 3.1.0.md * Merge branch 'master' into v3.1.0-dev * Added words relating to adopting semantics of JSON Schema (#2330) * Added words relating to adopting semantics of JSON Schema * Update versions/3.1.0.md Co-authored-by: Mike Ralphson * Update versions/3.1.0.md Co-authored-by: Mike Ralphson Co-authored-by: Darrel Miller Co-authored-by: Mike Ralphson * fix typo in release history table * fix link to style values in serialization table * Fix misspelling of a keyword in text (#2389) * Update wording that referred to the year 2019 as the current year (#2390) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema (#2394) * Added link to JSON Schema Validation docs explain which formats are included in JSON Schema * Update verbiage to be more accurate Co-authored-by: Mike Ralphson Co-authored-by: Mike Ralphson * Update 3.1.0.md (#2405) Improve wording about 'summary' and 'description' in Reference Object * long descriptions are cool too (#2408) Co-authored-by: Phil Sturgeon * Unescaped Slashes Aint Welcome Around 'Ere (#2218) * oas 3.0 doesn't mention slashes not allowed * none of those either Co-authored-by: Phil Sturgeon * Add missing field and use same summaries in Request Body Examples. (#2362) * Add missing schema type in Operation Object YAML Example. (#2361) * OAS schema dialect clarifications (#2399) * OAS schema dialect clarifications * OAS schema dialect clarifications Signed-off-by: Mike Ralphson * $schema is allowed in subschemas when bundling Co-authored-by: Ben Hutton * Schema dialect clarifications from Ben Signed-off-by: Mike Ralphson * Use top-level jsonSchemaDialect field Co-authored-by: Ben Hutton * Update JSON Schema Draft to 2020-12 and make $ref resolution rules explicit (#2437) * fix http link to json-schema.org Signed-off-by: Mike Ralphson * fix http link to spec.commonmark.org Signed-off-by: Mike Ralphson * Specify rules for $ref resolution Signed-off-by: Mike Ralphson * Specify relative resolution rules for pathItem $ref and example externalValue Signed-off-by: Mike Ralphson * Update JSON Schema draft links to 2020-12 IETF pages Signed-off-by: Mike Ralphson * Make language about 'MUST be in the form of a ...' consistent Signed-off-by: Mike Ralphson * Make it clear pathItem $refs don't need to be external now Signed-off-by: Mike Ralphson * Make RFC links consistent with regard to spacing Signed-off-by: Mike Ralphson * Allow a URI for example.externalValue fields This makes it fall under the rules for relative references. Signed-off-by: Mike Ralphson * Explicitly call out $ref as a Relative Reference * Remove wording about what implementations SHOULD/MAY do with a $ref * Prefer 'referenced document' to 'referrant document' for clarity * Fix JSON Schema $ref resolution fallback rule * Add links back to #relativeReferences definition * Split #relativeReferences definition into URL and URI sections Signed-off-by: Mike Ralphson * Clean-up wording about $refs in responsesObjects, fixes #1679 (#2442) * Clean-up wording about $refs in responsesObjects, fixes #1679 * Agreed to remove explicit verbiage around $refs in responseObjects, fixes #1679 * fix: two typos in versions/3.1.0.md (#2452) * Fix, clarify, and simplify content type schemas (#2351) * Fix, clarify, and simplify content type schemas This fixes #2349, which caught that an encoded PNG image is encoded into a text media type. In the process I realized some other errors, and simplified things. * HTTP `Content-Type` is always handled by OAS * Media Type Object key in most cases * Encoding object (possibly inferred from schema) in `multipart/form-data` * HTTP-level `Content-Encoding` is always handled by the OAS Header Object * JSON Schema "content*" is used for embedding one media type into another * the encoded resource is of media type `text/plain` * `"contentMediaType"` is the embedded media type after decoding * `"contentEncoding"` is how to encode/decode binary to/from text This removes any chance of `"contentMediaType"` conflicting with the Media Type Object key or with `contentType` in the Encoding Object, as they now always do different things. Likewise, the HTTP `Content-Encoding` header (with values like gzip, deflate, etc.) does different things than `"contentEncoding"` (which has values like base64, base64url, quoted-printable, etc.). The deprecated part header `Content-Transfer-Encoding` is likewise handled in the Encoding Object, but is probably never used. * Fix Content-Type to indicate semantics ...rather than literal content format on the wire. * Update 3.1.0.md Fixed a typo and changed a SHOULD to MAY. * Update versions/3.1.0.md * clarify default encoding content type value. * Describe interaction between JSON Schema contentEncoding and HTTP Content-Encoding header Co-authored-by: Mike Kistler Co-authored-by: Darrel Co-authored-by: Mike Kistler * 3.1.0 release prep (#2461) * 3.1.0 release prep * Update README.md * reframing `user` as `author` (#2463) Per comment in review, authors determine whether a spec is a single or multipart document. Those who consume the spec care more about the information itself and less (or not at all directly) about how it was assembled. * fixed the dash character Co-authored-by: Mike Ralphson Co-authored-by: Roberto Polli Co-authored-by: Axel Nennker Co-authored-by: Phil Sturgeon Co-authored-by: Mike Kistler Co-authored-by: Darrel Co-authored-by: Arhimenrius Co-authored-by: Lorna Jane Mitchell Co-authored-by: Henry Andrews Co-authored-by: Alan Crosswell Co-authored-by: Helen Kosova Co-authored-by: seiya Co-authored-by: Adam Leventhal Co-authored-by: Sebastián Ramírez Co-authored-by: Patrice Krakow Co-authored-by: Ted Epstein Co-authored-by: Carsten Brandt Co-authored-by: Sergej Co-authored-by: nasa9084 Co-authored-by: Erik Wilde Co-authored-by: Marsh Gardiner Co-authored-by: Phil Sturgeon Co-authored-by: Karen Etheridge Co-authored-by: Ben Hutton Co-authored-by: Sebastien Rosset Co-authored-by: Darrel Miller Co-authored-by: Vladimir Gorej Co-authored-by: Helen Kosova Co-authored-by: Deven Phillips Co-authored-by: Vladimir Co-authored-by: Quint Daenen --- README.md | 18 ++--- versions/3.1.0.md | 170 +++++++++++++++++++++++++++------------------- 2 files changed, 107 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index e8f9f8e39b..0a81ca7f21 100644 --- a/README.md +++ b/README.md @@ -11,32 +11,28 @@ The OpenAPI Specification (OAS) defines a standard, programming language-agnosti 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. +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.0.3 +## Current Version - 3.1.0 -The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md). - -## Current Release Candidate Version - 3.1.0-RC1 - -We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC1](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). +The current version of the OpenAPI specification is [OpenAPI Specification 3.1.0](versions/3.1.0.md). ### Previous Versions -This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to "OpenAPI Specification", as well as the Swagger 1.2 and Swagger 2.0 specifications. +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/v3.0). +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 3.0 implementations](IMPLEMENTATIONS.md). +[list of implementations](IMPLEMENTATIONS.md). ## Participation @@ -48,7 +44,7 @@ The TSC holds weekly web conferences to review open pull requests and discuss op 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.0.3.md). The human-readable markdown file _is the source of truth_ for the specification. +* 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. diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 11a7abfc25..39425bd6b9 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1,6 +1,6 @@ # OpenAPI Specification -#### Version 3.1.0-rc1 +#### 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. @@ -26,7 +26,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp - [Document Structure](#documentStructure) - [Data Types](#dataTypes) - [Rich Text Formatting](#richText) - - [Relative References In URIs](#relativeReferences) + - [Relative References In URIs](#relativeReferencesURI) + - [Relative References In URLs](#relativeReferencesURL) - [Schema](#schema) - [OpenAPI Object](#oasObject) - [Info Object](#infoObject) @@ -75,6 +76,8 @@ Path templating refers to the usage of template expressions, delimited by curly 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). @@ -133,17 +136,17 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA ### 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. +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 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2). +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 2019-09. +Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. -As defined by JSON Schema, data types can have an optional modifier property: `format`. +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: @@ -160,12 +163,20 @@ The formats defined by the OAS are: 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 +### 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 are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI. This includes relative references in [`Reference Objects`](#referenceObject), outside of any [`Schema Object`](#schemaObject). -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 2019-09](https://json-schema.org/draft/2019-09/json-schema-core.html). If no parent schema contains an `$id`, then the Base URI is determined as in the previous paragraph. +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 @@ -181,6 +192,7 @@ 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. @@ -203,8 +215,8 @@ Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the API. summary | `string` | A short summary 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. +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). @@ -257,8 +269,8 @@ Contact information for the exposed API. 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. +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). @@ -288,7 +300,7 @@ 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. MUST be in the format of a URL. The `url` field is mutually exclusive of the `identifier` 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). @@ -640,7 +652,6 @@ components: read:pets: read your pets ``` - #### Paths Object Holds the relative paths to the individual endpoints and their operations. @@ -729,7 +740,7 @@ The path itself is still exposed to the documentation viewer but they will not k 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. +$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. @@ -936,6 +947,7 @@ requestBody: content: 'application/x-www-form-urlencoded': schema: + type: object properties: name: description: Updated name of the pet @@ -971,8 +983,8 @@ Allows referencing an external resource for extended documentation. 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. +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). @@ -1035,7 +1047,7 @@ 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 +##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. @@ -1061,7 +1073,7 @@ Assume a parameter named `color` has one of the following values: ``` The following table shows examples of rendering differences for each value. -[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` +[`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 @@ -1312,12 +1324,12 @@ content: $ref: '#/components/schemas/User' examples: user: - summary: User Example in XML + summary: User example in XML externalValue: 'https://foo.bar/examples/user-example.xml' 'text/plain': examples: user: - summary: User example in text plain format + summary: User example in Plain text externalValue: 'https://foo.bar/examples/user-example.txt' '*/*': examples: @@ -1330,6 +1342,7 @@ A body parameter that is an array of string values: ```json { "description": "user to add to the system", + "required": true, "content": { "text/plain": { "schema": { @@ -1433,14 +1446,15 @@ application/json: ##### 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, such schemas use the `contentEncoding` JSON Schema keyword rather than the `format` keyword. This 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). +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. +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) SHOULD omit `schema`, as no JSON Schema type is suitable: +Content transferred in binary (octet-stream) MAY omit `schema`: ```yaml # a PNG image as a binary file: @@ -1461,9 +1475,12 @@ 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: @@ -1496,10 +1513,11 @@ requestBody: # The property name 'file' will be used for all files. file: type: array - items: - contentMediaType: application/octet-stream + 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 @@ -1529,16 +1547,15 @@ When passing complex objects in the `application/x-www-form-urlencoded` 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 [RFC 7578](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). +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`: +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` -* If the JSON Schema keyword `contentMediaType` is used and no Encoding Object is present, then the Content-Type is that which is specified by `contentMediaType`, however if an Encoding Object is present, then `contentMediaType` SHALL be ignored -As with non-multipart request or response bodies, when using `contentMediaType` to specify a binary Content-Type without also using `contentEncoding`, the JSON Schema `type` keyword is omitted. +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: @@ -1557,15 +1574,17 @@ requestBody: type: object properties: {} profileImage: - # Content-Type with contentMediaType is the contentMediaType (image/png here) + # 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) + # 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) + # default Content-Type for arrays is based on the _inner_ type (object shown, so `application/json` in this example) type: array items: type: object @@ -1581,7 +1600,7 @@ 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: when `type` is absent and `contentMediaType` is present - the value of `contentMediaType`; when both `type` and `contentMediaType` are absent - `application/octet-stream`; for `string` with a `contentEncoding` - `application/octet-string`; 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. +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. @@ -1594,7 +1613,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml requestBody: content: - multipart/mixed: + multipart/form-data: schema: type: object properties: @@ -1611,9 +1630,7 @@ requestBody: description: metadata in XML format type: object properties: {} - profileImage: - type: string - contentMediaType: image/jpeg + profileImage: {} encoding: historyMetadata: # require XML Content-Type in utf-8 encoding @@ -1646,12 +1663,12 @@ 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. +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. 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. +[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). @@ -1707,7 +1724,7 @@ Describes a single response from an API Operation, including design-time, static ##### 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. +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). @@ -1939,7 +1956,7 @@ 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. +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). @@ -2019,7 +2036,7 @@ For computing links, and providing instructions to execute them, a [runtime expr 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. +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. @@ -2156,7 +2173,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org "^" / "_" / "`" / "|" / "~" / 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). +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. @@ -2213,7 +2230,7 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object 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. +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). @@ -2235,14 +2252,18 @@ description: Pets operations #### Reference Object -A simple object to allow referencing other objects in the OpenAPI document, internally and externally. Targets of a reference do not need to be contained in a components section and for external references, targets MAY exist within any compatible resource. Targets are subject to the same constraints as inline objects. +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 string. -summary | `string` | A short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not define 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 define a `description` field, then this field has no effect. +$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. @@ -2284,24 +2305,30 @@ $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 2019-09](http://json-schema.org/). +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://json-schema.org/draft/2019-09/json-schema-core.html) and [JSON Schema Validation](https://json-schema.org/draft/2019-09/json-schema-validation.html). +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 the JSON Schema. +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 is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such any keyword available for those vocabularies is by definition available in OpenAPI, and will work the exact same way. +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 definition but their definitions were adjusted to the OpenAPI Specification. +The following properties are taken from the JSON Schema specification but their definitions have been extended by the OAS: -- description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. +- 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 defined in the vocabularies defined in the JSON Schema Core and JSON Schema Validation specifications, any properties can be used from any vocabularies, or entirely arbitrary keywords. The OpenAPI Specification defines an additional vocabulary of keywords which MAY be used along with the JSON Schema vocabulary keywords for further schema description: +In addition to the JSON Schema properties comprising the OAS dialect, the Schema Object supports keywords from any other vocabularies, or entirely arbitrary properties. -##### Fixed Fields +The OpenAPI Specification's base vocabulary is comprised of the following keywords: + +##### Fixed Fields Field Name | Type | Description ---|:---:|--- @@ -2310,7 +2337,7 @@ Field Name | Type | Description 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). +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) @@ -2331,13 +2358,15 @@ As such, inline schema definitions, which do not have a given id, *cannot* be us 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. -###### Picking Schema Vocabularies +###### 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. -It is important for tooling to be able to detect what meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema Object, 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`. -`$schema` MAY be present in any Schema Object, and if present MUST be used to determine which dialect should be used when processing the 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 `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. +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 @@ -2799,7 +2828,7 @@ will indicate that the `Cat` schema be used. Likewise this schema: } ``` -will map to `Dog` because of the definition in the `mappings` element. +will map to `Dog` because of the definition in the `mapping` element. #### XML Object @@ -2813,7 +2842,7 @@ See examples for expected behavior. 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. +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`). @@ -3160,13 +3189,13 @@ animals: 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 currently (2019) the implicit flow is about to be deprecated [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/id/draft-ietf-oauth-security-topics). Recommended for most use case is Authorization Code Grant flow with PKCE. +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 short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +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). @@ -3401,7 +3430,7 @@ The extensions properties are implemented as patterned fields that are always pr 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-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. Can have any valid JSON format value. +^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). @@ -3422,7 +3451,8 @@ Two examples of this: Version | Date | Notes --- | --- | --- -3.1.0-rc0 | 2020-10-08 | rc1 of the 3.1 specification +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 From f7ef3c942660e0a7c5a54667173ef2b9537291d3 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 2 Mar 2021 14:39:49 -0800 Subject: [PATCH 19/90] Add schemas for 3.1 --- .gitmodules | 3 + package.json | 3 + schemas/v3.1/README.md | 35 + schemas/v3.1/dialect/base.schema.json | 27 + schemas/v3.1/meta/base.schema.json | 79 ++ schemas/v3.1/openapi3-examples | 1 + schemas/v3.1/schema.json | 1327 +++++++++++++++++++++++++ schemas/v3.1/schema.yaml | 902 +++++++++++++++++ schemas/v3.1/test.js | 50 + schemas/v3.1/validate.js | 30 + 10 files changed, 2457 insertions(+) create mode 100644 .gitmodules create mode 100644 schemas/v3.1/README.md create mode 100644 schemas/v3.1/dialect/base.schema.json create mode 100644 schemas/v3.1/meta/base.schema.json create mode 160000 schemas/v3.1/openapi3-examples create mode 100644 schemas/v3.1/schema.json create mode 100644 schemas/v3.1/schema.yaml create mode 100644 schemas/v3.1/test.js create mode 100644 schemas/v3.1/validate.js diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..93a5196406 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "schemas/v3.1/openapi3-examples"] + path = schemas/v3.1/openapi3-examples + url = git@github.com:Mermade/openapi3-examples.git diff --git a/package.json b/package.json index 01be1c8d5c..59851cb7dc 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,10 @@ ], "dependencies": {}, "devDependencies": { + "@hyperjump/json-schema": "^0.17.0", + "chai": "^4.3.1", "mdv": "^1.0.7", + "mocha": "^8.3.0", "yaml": "^1.8.3" }, "keywords": [ diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md new file mode 100644 index 0000000000..04eba1cec1 --- /dev/null +++ b/schemas/v3.1/README.md @@ -0,0 +1,35 @@ +# OpenAPI 3.1.X JSON Schema + +Here you can find the JSON Schema for validating OpenAPI definitions of versions +3.1.X. + +As a reminder, the JSON Schema is not the source of truth for the Specification. +In cases of conflicts between the Specification itself and the JSON Schema, the +Specification wins. Also, some Specification constraints cannot be represented +with the JSON Schema so it's highly recommended to employ other methods to +ensure compliance. + +The iteration version of the JSON Schema can be found in the `$id` field. For +example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` +means this iteration was created on March 2nd, 2021. + +To submit improvements to the schema, modify the schema.yaml file only. + +The TSC will then: +- Run tests on the updated schema +- Update the iteration version +- Convert the schema.yaml to schema.json +- Publish the new version + +## Tests +The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. + +```bash +npx mocha test.js +``` + +You can also validate a document individually. + +```bash +node validate.js path/to/document/to/validate.yaml +``` diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json new file mode 100644 index 0000000000..1f65d64e5d --- /dev/null +++ b/schemas/v3.1/dialect/base.schema.json @@ -0,0 +1,27 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/dialect/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://json-schema.org/draft/2020-12/vocab/core": true, + "https://json-schema.org/draft/2020-12/vocab/applicator": true, + "https://json-schema.org/draft/2020-12/vocab/unevaluated": true, + "https://json-schema.org/draft/2020-12/vocab/validation": true, + "https://json-schema.org/draft/2020-12/vocab/meta-data": true, + "https://json-schema.org/draft/2020-12/vocab/format-annotation": true, + "https://json-schema.org/draft/2020-12/vocab/content": true, + "https://spec.openapis.org/oas/3.1/vocab/base": false + }, + "$dynamicAnchor": "meta", + + "title": "OpenAPI 3.1 Schema Object Dialect", + "allOf": [ + { "$ref": "https://json-schema.org/draft/2020-12/meta/core" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/applicator" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/unevaluated" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/validation" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/meta-data" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/format-annotation" }, + { "$ref": "https://json-schema.org/draft/2020-12/meta/content" }, + { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } + ] +} diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json new file mode 100644 index 0000000000..00c127dc48 --- /dev/null +++ b/schemas/v3.1/meta/base.schema.json @@ -0,0 +1,79 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/meta/base", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$vocabulary": { + "https://spec.openapis.org/oas/3.1/vocab/base": true + }, + "$dynamicAnchor": "meta", + "title": "OAS Base vocabulary", + + "type": ["object", "boolean"], + "properties": { + "example": true, + "discriminator": { "$ref": "#/$defs/Discriminator" }, + "externalDocs": { "$ref": "#/$defs/ExternalDocs" }, + "xml": { "$ref": "#/$defs/Xml" } + }, + "$defs": { + "Extensible": { + "patternProperties": { + "^x-": true + } + }, + "Discriminator": { + "$ref": "#/$defs/Extensible", + "type": "object", + "properties": { + "propertyName": { + "type": "string" + }, + "mapping": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": ["propertyName"], + "unevaluatedProperties": false + }, + "ExternalDocs": { + "$ref": "#/$defs/Extensible", + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri-reference" + }, + "description": { + "type": "string" + } + }, + "required": ["url"], + "unevaluatedProperties": false + }, + "Xml": { + "$ref": "#/$defs/Extensible", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string", + "format": "uri" + }, + "prefix": { + "type": "string" + }, + "attribute": { + "type": "boolean" + }, + "wrapped": { + "type": "boolean" + } + }, + "unevaluatedProperties": false + } + } +} diff --git a/schemas/v3.1/openapi3-examples b/schemas/v3.1/openapi3-examples new file mode 160000 index 0000000000..9c2997e1a2 --- /dev/null +++ b/schemas/v3.1/openapi3-examples @@ -0,0 +1 @@ +Subproject commit 9c2997e1a25919a8182080cc43a4db06d2dc775d diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json new file mode 100644 index 0000000000..a6117cfa3d --- /dev/null +++ b/schemas/v3.1/schema.json @@ -0,0 +1,1327 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "properties": { + "openapi": { + "type": "string" + }, + "info": { + "$ref": "#/$defs/info" + }, + "jsonSchemaDialect": { + "type": "string" + }, + "servers": { + "$ref": "#/$defs/server" + }, + "paths": { + "$ref": "#/$defs/paths" + }, + "webhooks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "components": { + "$ref": "#/$defs/components" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/$defs/tag" + } + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "openapi", + "info" + ], + "anyOf": [ + { + "required": [ + "paths" + ] + }, + { + "required": [ + "components" + ] + }, + { + "required": [ + "webhooks" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "info": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "termsOfService": { + "type": "string" + }, + "contact\"": { + "$ref": "#/$defs/contact" + }, + "license": { + "$ref": "#/$defs/license" + }, + "version": { + "type": "string" + } + }, + "required": [ + "title", + "version" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "contact": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "url": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "license": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "identifier": { + "type": "string" + }, + "url": { + "$ref\"": "#/$defs/uri" + } + }, + "required": [ + "name" + ], + "oneOf": [ + { + "required": [ + "identifier" + ] + }, + { + "required": [ + "url" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server": { + "type": "object", + "properties": { + "url": { + "$ref": "#/$defs/uri" + }, + "description": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/server-variable" + } + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "server-variable": { + "type": "object", + "properties": { + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "default": { + "type": "string" + }, + "descriptions": { + "type": "string" + } + }, + "required": [ + "default" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "components": { + "type": "object", + "properties": { + "schemas": { + "type": "object", + "additionalProperties": { + "$dynamicRef": "#meta" + } + }, + "responses": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/response-or-reference" + } + }, + "parameters": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/parameter-or-reference" + } + }, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + }, + "requestBodies": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/request-body-or-reference" + } + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref\"": "#/$defs/header-or-reference" + } + }, + "securitySchemes": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/security-scheme-or-reference" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "pathItems": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + } + }, + "patternProperties": { + "": { + "propertyNames": { + "pattern": "^[a-zA-Z0-9._-]+$" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "paths": { + "type": "object", + "patternProperties": { + "^/": { + "$ref": "#/$defs/path-item" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + }, + "parameters": { + "type": "array", + "items": { + "$ref": "#/$defs/parameter-or-reference" + } + } + }, + "patternProperties": { + "^get|post|delete|options|head|patch|trace$": { + "$ref": "#/$defs/operation" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "path-item-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/path-item" + } + }, + "operation": { + "type": "object", + "properties": { + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + }, + "operationId": { + "type": "string" + }, + "parameters": { + "type": "array", + "items": { + "$ref\"": "#/$defs/parameter-or-reference" + } + }, + "requestBody": { + "$ref": "#/$defs/request-body-or-reference" + }, + "responses": { + "$ref": "#/$defs/responses" + }, + "callbacks": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/callbacks-or-reference" + } + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "security": { + "type": "array", + "items": { + "$ref": "#/$defs/security-requirement" + } + }, + "servers": { + "type": "array", + "items": { + "$ref": "#/$defs/server" + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "external-documentation": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "url": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "path", + "cookie" + ] + }, + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "in" + ], + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "type": "string" + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + } + }, + "allOf": [ + { + "$ref": "#/$defs/examples" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie" + }, + { + "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form" + } + ], + "$defs": { + "styles-for-path": { + "if": { + "properties": { + "in": { + "const": "path" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "matrix", + "label", + "simple" + ] + }, + "required": { + "const": true + } + }, + "required": [ + "required" + ] + } + }, + "styles-for-header": { + "if": { + "properties": { + "in": { + "const": "header" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + } + } + } + }, + "styles-for-query": { + "if": { + "properties": { + "in": { + "const": "query" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + } + } + } + }, + "styles-for-cookie": { + "if": { + "properties": { + "in": { + "const": "cookie" + } + }, + "required": [ + "in" + ] + }, + "then": { + "properties": { + "style": { + "default": "form", + "enum": [ + "form" + ] + } + } + } + }, + "styles-for-form": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + }, + "content": { + "properties": { + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + } + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "parameter-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/parameter" + } + }, + "request-body": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + } + }, + "required": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "content" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "request-body-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/request-body" + } + }, + "media-type": { + "type": "object", + "properties": { + "schema": { + "$dynamicRef": "#meta" + }, + "encoding": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/encoding" + } + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/examples" + } + ], + "unevaluatedProperties": false + }, + "encoding": { + "type": "object", + "properties": { + "contentType": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "style": { + "default": "form", + "enum": [ + "form", + "spaceDelimited", + "pipeDelimited", + "deepObject" + ] + }, + "explode": { + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + } + }, + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/encoding/$defs/explode-default" + } + ], + "unevaluatedProperties": false, + "$defs": { + "explode-default": { + "if": { + "properties": { + "style": { + "const": "form" + } + }, + "required": [ + "style" + ] + }, + "then": { + "properties": { + "explode": { + "default": true + } + } + }, + "else": { + "properties": { + "explode": { + "default": false + } + } + } + } + } + }, + "responses": { + "type": "object", + "properties": { + "default": { + "$ref": "#/$defs/response-or-reference" + } + }, + "patternProperties": { + "[1-5][0-9X]{2}": { + "$ref": "#/$defs/response-or-reference" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "headers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/header-or-reference" + } + }, + "content": { + "type": "object", + "addtionalProperties": { + "$ref": "#/$defs/media-type" + } + }, + "links": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/link-or-reference" + } + } + }, + "required": [ + "description" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "response-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/response" + } + }, + "callbacks": { + "type": "object", + "$ref": "#/$defs/specification-extensions", + "additionalProperties": { + "$ref": "#/$defs/path-item-or-reference" + } + }, + "callbacks-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/callbacks" + } + }, + "example": { + "type": "object", + "properties": { + "summary": { + "type": "string" + }, + "description": { + "type": "string" + }, + "value": true, + "externalValue": { + "$ref": "#/$defs/uri" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "example-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/example" + } + }, + "link": { + "type": "object", + "properties": { + "operationRef": { + "$ref": "#/$defs/uri" + }, + "operationId": true, + "parameters": { + "$ref": "#/$defs/map-of-strings" + }, + "requestBody": true, + "description": { + "type": "string" + }, + "body": { + "$ref": "#/$defs/server" + } + }, + "oneOf": [ + { + "required": [ + "operationRef" + ] + }, + { + "required": [ + "operationId" + ] + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "link-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/link" + } + }, + "header": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "required": { + "default": false, + "type": "boolean" + }, + "deprecated": { + "default": false, + "type": "boolean" + }, + "allowEmptyValue": { + "default": false, + "type": "boolean" + } + }, + "dependentSchemas": { + "schema": { + "properties": { + "style": { + "default": "simple", + "enum": [ + "simple" + ] + }, + "explode": { + "default": false, + "type": "boolean" + }, + "allowReserved": { + "default": false, + "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + } + }, + "$ref": "#/$defs/examples" + }, + "content": { + "properties": { + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + } + } + } + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "header-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/header" + } + }, + "tag": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "externalDocs": { + "$ref": "#/$defs/external-documentation" + } + }, + "required": [ + "name" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "reference": { + "type": "object", + "properties": { + "$ref": { + "$ref": "#/$defs/uri" + }, + "summary": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "unevaluatedProperties": false + }, + "schema": { + "$dynamicAnchor": "meta", + "$ref": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "security-scheme": { + "type": "object", + "properties": { + "type": { + "enum": [ + "apiKey", + "http", + "mutualTLS", + "oauth2", + "openIdConnect" + ] + }, + "description": { + "type": "string" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/specification-extensions" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-apikey" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-http-bearer" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oauth2" + }, + { + "$ref": "#/$defs/security-scheme/$defs/type-oidc" + } + ], + "unevaluatedProperties": false, + "$defs": { + "type-apikey": { + "if": { + "properties": { + "type": { + "const": "apiKey" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "name": { + "type": "string" + }, + "in": { + "enum": [ + "query", + "header", + "cookie" + ] + } + }, + "required": [ + "name", + "in" + ] + } + }, + "type-http": { + "if": { + "properties": { + "type": { + "const": "http" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "scheme": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-http-bearer": { + "if": { + "properties": { + "type": { + "const": "http" + }, + "scheme": { + "const": "bearer" + } + }, + "required": [ + "type", + "scheme" + ] + }, + "then": { + "properties": { + "bearerFormat": { + "type": "string" + } + }, + "required": [ + "scheme" + ] + } + }, + "type-oauth2": { + "if": { + "properties": { + "type": { + "const": "oauth2" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "flows": { + "$ref": "#/$defs/oauth-flows" + } + }, + "required": [ + "flows" + ] + } + }, + "type-oidc": { + "if": { + "properties": { + "type": { + "const": "openIdConnect" + } + }, + "required": [ + "type" + ] + }, + "then": { + "properties": { + "openIdConnectUrl": { + "$ref": "#/$defs/uri" + } + }, + "required": [ + "openIdConnectUrl" + ] + } + } + } + }, + "security-scheme-or-reference": { + "if": { + "required": [ + "$ref" + ] + }, + "then": { + "$ref": "#/$defs/reference" + }, + "else": { + "$ref": "#/$defs/security-scheme" + } + }, + "oauth-flows": { + "type": "object", + "properties": { + "implicit": { + "$ref": "#/$defs/oauth-flows/$defs/implicit" + }, + "password": { + "$ref": "#/$defs/oauth-flows/$defs/password" + }, + "clientCredentials": { + "$ref\"": "#/$defs/oauth-flows/$defs/client-credentials" + }, + "authorizationCode": { + "$ref": "#/$defs/oauth-flows/$defs/authorization-code" + } + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false, + "$defs": { + "implicit": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "password": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "client-credentials": { + "type": "object", + "properties": { + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "authorization-code": { + "type": "object", + "properties": { + "authorizationUrl": { + "type": "string" + }, + "tokenUrl": { + "type": "string" + }, + "refreshUrl": { + "type": "string" + }, + "scopes": { + "$ref": "#/$defs/map-of-strings" + } + }, + "required": [ + "authorizationUrl", + "tokenUrl", + "scopes" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + } + } + }, + "security-requirement": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "specification-extensions": { + "patternProperties": { + "^x-": true + } + }, + "examples": { + "properties": { + "example": true, + "examples": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/example-or-reference" + } + } + } + }, + "uri": { + "type": "string", + "format": "uri" + }, + "map-of-strings": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } +} diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml new file mode 100644 index 0000000000..e342298091 --- /dev/null +++ b/schemas/v3.1/schema.yaml @@ -0,0 +1,902 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +properties: + openapi: + type: string + info: + $ref: '#/$defs/info' + jsonSchemaDialect: + type: string + servers: + $ref: '#/$defs/server' + paths: + $ref: '#/$defs/paths' + webhooks: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + components: + $ref: '#/$defs/components' + security: + type: array + items: + $ref: '#/$defs/security-requirement' + tags: + type: array + items: + $ref: '#/$defs/tag' + externalDocs: + $ref: '#/$defs/external-documentation' +required: + - openapi + - info +anyOf: + - required: + - paths + - required: + - components + - required: + - webhooks +$ref: '#/$defs/specification-extensions' +unevaluatedProperties: false + +$defs: + info: + type: object + properties: + title: + type: string + summary: + type: string + description: + type: string + termsOfService: + type: string + contact": + $ref: '#/$defs/contact' + license: + $ref: '#/$defs/license' + version: + type: string + required: + - title + - version + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + contact: + type: object + properties: + name: + type: string + url: + type: string + email: + type: string + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + license: + type: object + properties: + name: + type: string + identifier: + type: string + url: + $ref": '#/$defs/uri' + required: + - name + oneOf: + - required: + - identifier + - required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server: + type: object + properties: + url: + $ref: '#/$defs/uri' + description: + type: string + variables: + type: object + additionalProperties: + $ref: '#/$defs/server-variable' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + server-variable: + type: object + properties: + enum: + type: array + items: + type: string + minItems: 1 + default: + type: string + descriptions: + type: string + required: + - default + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + components: + type: object + properties: + schemas: + type: object + additionalProperties: + $dynamicRef: '#meta' + responses: + type: object + additionalProperties: + $ref: '#/$defs/response-or-reference' + parameters: + type: object + additionalProperties: + $ref: '#/$defs/parameter-or-reference' + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + requestBodies: + type: object + additionalProperties: + $ref: '#/$defs/request-body-or-reference' + headers: + type: object + additionalProperties: + $ref": '#/$defs/header-or-reference' + securitySchemes: + type: object + additionalProperties: + $ref: '#/$defs/security-scheme-or-reference' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + pathItems: + type: object + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + patternProperties: + '': + propertyNames: + pattern: '^[a-zA-Z0-9._-]+$' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + paths: + type: object + patternProperties: + '^/': + $ref: '#/$defs/path-item' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item: + type: object + properties: + summary: + type: string + description: + type: string + servers: + type: array + items: + $ref: '#/$defs/server' + parameters: + type: array + items: + $ref: '#/$defs/parameter-or-reference' + patternProperties: + '^get|post|delete|options|head|patch|trace$': + $ref: '#/$defs/operation' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + path-item-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/path-item' + + operation: + type: object + properties: + tags: + type: array + items: + type: string + summary: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + operationId: + type: string + parameters: + type: array + items: + $ref": '#/$defs/parameter-or-reference' + requestBody: + $ref: '#/$defs/request-body-or-reference' + responses: + $ref: '#/$defs/responses' + callbacks: + type: object + additionalProperties: + $ref: '#/$defs/callbacks-or-reference' + deprecated: + default: false + type: boolean + security: + type: array + items: + $ref: '#/$defs/security-requirement' + servers: + type: array + items: + $ref: '#/$defs/server' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + external-documentation: + type: object + properties: + description: + type: string + url: + $ref: '#/$defs/uri' + required: + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter: + type: object + properties: + name: + type: string + in: + enum: + - query + - header + - path + - cookie + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + required: + - in + dependentSchemas: + schema: + properties: + style: + type: string + explode: + type: boolean + allowReserved: + default: false + type: "boolean" + schema: + $dynamicRef: '#meta' + allOf: + - $ref: '#/$defs/examples' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie' + - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form' + + $defs: + styles-for-path: + if: + properties: + in: + const: path + required: + - in + then: + properties: + style: + default: simple + enum: + - matrix + - label + - simple + required: + const: true + required: + - required + + styles-for-header: + if: + properties: + in: + const: header + required: + - in + then: + properties: + style: + default: simple + enum: + - simple + + styles-for-query: + if: + properties: + in: + const: query + required: + - in + then: + properties: + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + + styles-for-cookie: + if: + properties: + in: + const: cookie + required: + - in + then: + properties: + style: + default: form + enum: + - form + + styles-for-form: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + content: + properties: + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + parameter-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/parameter' + + request-body: + type: object + properties: + description: + type: string + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + required: + default: false + type: boolean + required: + - content + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + request-body-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/request-body' + + media-type: + type: object + properties: + schema: + $dynamicRef: '#meta' + encoding: + type: object + additionalProperties: + $ref: '#/$defs/encoding' + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/examples' + unevaluatedProperties: false + + encoding: + type: object + properties: + contentType: + type: string + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + style: + default: form + enum: + - form + - spaceDelimited + - pipeDelimited + - deepObject + explode: + type: boolean + allowReserved: + default: false + type: boolean + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/encoding/$defs/explode-default' + unevaluatedProperties: false + + $defs: + explode-default: + if: + properties: + style: + const: form + required: + - style + then: + properties: + explode: + default: true + else: + properties: + explode: + default: false + + responses: + type: object + properties: + default: + $ref: '#/$defs/response-or-reference' + patternProperties: + '[1-5][0-9X]{2}': + $ref: '#/$defs/response-or-reference' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response: + type: object + properties: + description: + type: string + headers: + type: object + additionalProperties: + $ref: '#/$defs/header-or-reference' + content: + type: object + addtionalProperties: + $ref: '#/$defs/media-type' + links: + type: object + additionalProperties: + $ref: '#/$defs/link-or-reference' + required: + - description + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + response-or-reference: + if: + required: + - $ref + then: + $ref: "#/$defs/reference" + else: + $ref: "#/$defs/response" + + callbacks: + type: object + $ref: '#/$defs/specification-extensions' + additionalProperties: + $ref: '#/$defs/path-item-or-reference' + + callbacks-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/callbacks' + + example: + type: object + properties: + summary: + type: string + description: + type: string + value: true + externalValue: + $ref: '#/$defs/uri' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + example-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/example' + + link: + type: object + properties: + operationRef: + $ref: '#/$defs/uri' + operationId: true + parameters: + $ref: '#/$defs/map-of-strings' + requestBody: true + description: + type: string + body: + $ref: '#/$defs/server' + oneOf: + - required: + - operationRef + - required: + - operationId + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + link-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/link' + + header: + type: object + properties: + description: + type: string + required: + default: false + type: boolean + deprecated: + default: false + type: boolean + allowEmptyValue: + default: false + type: boolean + dependentSchemas: + schema: + properties: + style: + default: simple + enum: + - simple + explode: + default: false + type: boolean + allowReserved: + default: false + type: boolean + schema: + $dynamicRef: '#meta' + $ref: '#/$defs/examples' + content: + properties: + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + header-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/header' + + tag: + type: object + properties: + name: + type: string + description: + type: string + externalDocs: + $ref: '#/$defs/external-documentation' + required: + - name + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + reference: + type: object + properties: + $ref: + $ref: '#/$defs/uri' + summary: + type: string + description: + type: string + unevaluatedProperties: false + + schema: + $dynamicAnchor: meta + $ref: 'https://spec.openapis.org/oas/3.1/dialect/base' + + security-scheme: + type: object + properties: + type: + enum: + - apiKey + - http + - mutualTLS + - oauth2 + - openIdConnect + description: + type: string + required: + - type + allOf: + - $ref: '#/$defs/specification-extensions' + - $ref: '#/$defs/security-scheme/$defs/type-apikey' + - $ref: '#/$defs/security-scheme/$defs/type-http' + - $ref: '#/$defs/security-scheme/$defs/type-http-bearer' + - $ref: '#/$defs/security-scheme/$defs/type-oauth2' + - $ref: '#/$defs/security-scheme/$defs/type-oidc' + unevaluatedProperties: false + + $defs: + type-apikey: + if: + properties: + type: + const: apiKey + required: + - type + then: + properties: + name: + type: string + in: + enum: + - query + - header + - cookie + required: + - name + - in + + type-http: + if: + properties: + type: + const: http + required: + - type + then: + properties: + scheme: + type: string + required: + - scheme + + type-http-bearer: + if: + properties: + type: + const: http + scheme: + const: bearer + required: + - type + - scheme + then: + properties: + bearerFormat: + type: string + required: + - scheme + + type-oauth2: + if: + properties: + type: + const: oauth2 + required: + - type + then: + properties: + flows: + $ref: '#/$defs/oauth-flows' + required: + - flows + + type-oidc: + if: + properties: + type: + const: openIdConnect + required: + - type + then: + properties: + openIdConnectUrl: + $ref: '#/$defs/uri' + required: + - openIdConnectUrl + + security-scheme-or-reference: + if: + required: + - $ref + then: + $ref: '#/$defs/reference' + else: + $ref: '#/$defs/security-scheme' + + oauth-flows: + type: object + properties: + implicit: + $ref: '#/$defs/oauth-flows/$defs/implicit' + password: + $ref: '#/$defs/oauth-flows/$defs/password' + clientCredentials: + $ref": '#/$defs/oauth-flows/$defs/client-credentials' + authorizationCode: + $ref: '#/$defs/oauth-flows/$defs/authorization-code' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + $defs: + implicit: + type: object + properties: + authorizationUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + password: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + client-credentials: + type: object + properties: + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + authorization-code: + type: object + properties: + authorizationUrl: + type: string + tokenUrl: + type: string + refreshUrl: + type: string + scopes: + $ref: '#/$defs/map-of-strings' + required: + - authorizationUrl + - tokenUrl + - scopes + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + + security-requirement: + type: object + additionalProperties: + type: array + items: + type: string + + specification-extensions: + patternProperties: + '^x-': true + + examples: + properties: + example: true + examples: + type: object + additionalProperties: + $ref: '#/$defs/example-or-reference' + + uri: + type: string + format: uri + + map-of-strings: + type: object + additionalProperties: + type: string diff --git a/schemas/v3.1/test.js b/schemas/v3.1/test.js new file mode 100644 index 0000000000..ca9e820865 --- /dev/null +++ b/schemas/v3.1/test.js @@ -0,0 +1,50 @@ +const fs = require("fs"); +const yaml = require("yaml"); +const JsonSchema = require("@hyperjump/json-schema"); +const { expect } = require("chai"); +const dialect = require("./dialect/base.schema.json"); +const vocabulary = require("./meta/base.schema.json"); + + +const testSuitePath = `${__dirname}/openapi3-examples/3.1`; + +JsonSchema.setMetaOutputFormat(JsonSchema.BASIC); +//JsonSchema.setShouldMetaValidate(false); + +let metaSchema; +before(async () => { + JsonSchema.add(dialect); + JsonSchema.add(vocabulary); + JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema.yaml`, "utf8"), { prettyErrors: true })); + metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02"); +}); + +describe("Pass", () => { + fs.readdirSync(`${testSuitePath}/pass`, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .forEach((entry) => { + const file = `${testSuitePath}/pass/${entry.name}`; + + it(entry.name, async () => { + const instance = yaml.parse(fs.readFileSync(file, "utf8")); + + const output = await JsonSchema.validate(metaSchema, instance, JsonSchema.BASIC); + expect(output.valid).to.equal(true); + }); + }); +}); + +describe("Fail", () => { + fs.readdirSync(`${testSuitePath}/fail`, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .forEach((entry) => { + const file = `${testSuitePath}/fail/${entry.name}`; + + it(entry.name, async () => { + const instance = yaml.parse(fs.readFileSync(file, "utf8")); + + const output = await JsonSchema.validate(metaSchema, instance); + expect(output.valid).to.equal(false); + }); + }); +}); diff --git a/schemas/v3.1/validate.js b/schemas/v3.1/validate.js new file mode 100644 index 0000000000..3a25e735ff --- /dev/null +++ b/schemas/v3.1/validate.js @@ -0,0 +1,30 @@ +const fs = require("fs"); +const yaml = require("yaml"); +const JsonSchema = require("@hyperjump/json-schema"); +const dialect = require("./dialect/base.schema.json"); +const vocabulary = require("./meta/base.schema.json"); + + +JsonSchema.setMetaOutputFormat(JsonSchema.BASIC); +//JsonSchema.setShouldMetaValidate(false); + +(async function () { + try { + // Compile / meta-validate + JsonSchema.add(dialect); + JsonSchema.add(vocabulary); + JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema.yaml`, "utf8"))); + const schema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02"); + const validateSchema = await JsonSchema.validate(schema); + + // Validate instance + const instance = yaml.parse(fs.readFileSync(`${__dirname}/${process.argv[2]}`, "utf8")); + const results = validateSchema(instance, JsonSchema.BASIC); + console.log(JSON.stringify(results, null, " ")); + } catch (error) { + console.log("************* Error ***************"); + console.log(error); + console.log(JSON.stringify(error.output, null, " ")); + //console.log(error.output); + } +}()); From eccada9d15930493328158ead26d30eb03383699 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 2 Mar 2021 17:24:37 -0800 Subject: [PATCH 20/90] 3.1 Schema: Extend schema to use OAS base vocabulary The main schema no longer validates schemas other than verifying that they are either a schema or an object. --- schemas/v3.1/README.md | 6 ++++++ schemas/v3.1/schema-base.json | 24 ++++++++++++++++++++++++ schemas/v3.1/schema-base.yaml | 17 +++++++++++++++++ schemas/v3.1/schema.yaml | 7 +++++-- schemas/v3.1/test.js | 3 ++- 5 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 schemas/v3.1/schema-base.json create mode 100644 schemas/v3.1/schema-base.yaml diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md index 04eba1cec1..141e3e919a 100644 --- a/schemas/v3.1/README.md +++ b/schemas/v3.1/README.md @@ -13,6 +13,12 @@ The iteration version of the JSON Schema can be found in the `$id` field. For example, the value of `$id: https://spec.openapis.org/oas/3.1/schema/2021-03-02` means this iteration was created on March 2nd, 2021. +The `schema.yaml` schema doesn't validate the JSON Schemas in your OpenAPI +document because 3.1 allows you to use any JSON Schema dialect you choose. We +have also included `schema-base.yaml` that extends the main schema to validate +that all schemas use the default OAS base vocabulary. + +## Contributing To submit improvements to the schema, modify the schema.yaml file only. The TSC will then: diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json new file mode 100644 index 0000000000..078af184fe --- /dev/null +++ b/schemas/v3.1/schema-base.json @@ -0,0 +1,24 @@ +{ + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-03-02", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "properties": { + "jsonSchemaDialect": { + "$ref": "#/$defs/dialect" + } + }, + "$defs": { + "dialect": { + "const": "https://spec.openapis.org/oas/3.1/dialect/base" + }, + "schema": { + "$dynamicAnchor": "meta", + "$ref\"": "https://spec.openapis.org/oas/3.1/dialect/base", + "properties": { + "$schema": { + "$ref": "#/$defs/dialect" + } + } + } + } +} diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml new file mode 100644 index 0000000000..41a27be7a9 --- /dev/null +++ b/schemas/v3.1/schema-base.yaml @@ -0,0 +1,17 @@ +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-03-02' +$schema: 'https://json-schema.org/draft/2020-12/schema' + +$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +properties: + jsonSchemaDialect: + $ref: '#/$defs/dialect' + +$defs: + dialect: + const: 'https://spec.openapis.org/oas/3.1/dialect/base' + schema: + $dynamicAnchor: meta + $ref": 'https://spec.openapis.org/oas/3.1/dialect/base' + properties: + $schema: + $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index e342298091..3897e40429 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -7,7 +7,8 @@ properties: info: $ref: '#/$defs/info' jsonSchemaDialect: - type: string + $ref: '#/$defs/uri' + default: 'https://spec.openapis.org/oas/3.1/dialect/base' servers: $ref: '#/$defs/server' paths: @@ -681,7 +682,9 @@ $defs: schema: $dynamicAnchor: meta - $ref: 'https://spec.openapis.org/oas/3.1/dialect/base' + type: + - object + - boolean security-scheme: type: object diff --git a/schemas/v3.1/test.js b/schemas/v3.1/test.js index ca9e820865..2c5bb2fd1e 100644 --- a/schemas/v3.1/test.js +++ b/schemas/v3.1/test.js @@ -16,7 +16,8 @@ before(async () => { JsonSchema.add(dialect); JsonSchema.add(vocabulary); JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema.yaml`, "utf8"), { prettyErrors: true })); - metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02"); + JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema-base.yaml`, "utf8"), { prettyErrors: true })); + metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema-base/2021-03-02"); }); describe("Pass", () => { From bd7a645620dd39be05d65ae8adaa22a12bdccfff Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 3 Mar 2021 13:05:58 -0800 Subject: [PATCH 21/90] 3.1 Schema: Move scripts and tests to root --- .gitmodules | 4 +- schemas/v3.1/README.md | 4 +- schemas/v3.1/validate.js | 30 ------------ scripts/validate.js | 58 +++++++++++++++++++++++ {schemas/v3.1 => tests}/openapi3-examples | 0 {schemas => tests}/v3.1/test.js | 11 ++--- 6 files changed, 67 insertions(+), 40 deletions(-) delete mode 100644 schemas/v3.1/validate.js create mode 100755 scripts/validate.js rename {schemas/v3.1 => tests}/openapi3-examples (100%) rename {schemas => tests}/v3.1/test.js (76%) diff --git a/.gitmodules b/.gitmodules index 93a5196406..ca8320435d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,3 @@ -[submodule "schemas/v3.1/openapi3-examples"] - path = schemas/v3.1/openapi3-examples +[submodule "tests/v3.1/openapi3-examples"] + path = tests/openapi3-examples url = git@github.com:Mermade/openapi3-examples.git diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md index 141e3e919a..4f305d0754 100644 --- a/schemas/v3.1/README.md +++ b/schemas/v3.1/README.md @@ -31,11 +31,11 @@ The TSC will then: The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. ```bash -npx mocha test.js +npx mocha --recursive [repo root]/tests ``` You can also validate a document individually. ```bash -node validate.js path/to/document/to/validate.yaml +node [repo root]/scripts/validate.js path/to/document/to/validate.yaml ``` diff --git a/schemas/v3.1/validate.js b/schemas/v3.1/validate.js deleted file mode 100644 index 3a25e735ff..0000000000 --- a/schemas/v3.1/validate.js +++ /dev/null @@ -1,30 +0,0 @@ -const fs = require("fs"); -const yaml = require("yaml"); -const JsonSchema = require("@hyperjump/json-schema"); -const dialect = require("./dialect/base.schema.json"); -const vocabulary = require("./meta/base.schema.json"); - - -JsonSchema.setMetaOutputFormat(JsonSchema.BASIC); -//JsonSchema.setShouldMetaValidate(false); - -(async function () { - try { - // Compile / meta-validate - JsonSchema.add(dialect); - JsonSchema.add(vocabulary); - JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema.yaml`, "utf8"))); - const schema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02"); - const validateSchema = await JsonSchema.validate(schema); - - // Validate instance - const instance = yaml.parse(fs.readFileSync(`${__dirname}/${process.argv[2]}`, "utf8")); - const results = validateSchema(instance, JsonSchema.BASIC); - console.log(JSON.stringify(results, null, " ")); - } catch (error) { - console.log("************* Error ***************"); - console.log(error); - console.log(JSON.stringify(error.output, null, " ")); - //console.log(error.output); - } -}()); diff --git a/scripts/validate.js b/scripts/validate.js new file mode 100755 index 0000000000..cf1c2d09ca --- /dev/null +++ b/scripts/validate.js @@ -0,0 +1,58 @@ +#!/usr/bin/env node + +const fs = require("fs"); +const yaml = require("yaml"); +const JsonSchema = require("@hyperjump/json-schema"); +const dialect = require("../schemas/v3.1/dialect/base.schema.json"); +const vocabulary = require("../schemas/v3.1/meta/base.schema.json"); + + +if (process.argv.length < 3) { + console.log("Usage: validate [--schema=schema] [--version=2021-03-02] [--format=BASIC] path-to-file.yaml"); + console.log("\t--schema: (Default: schema) The name of the yaml schema file to use"); + console.log("\t--version: (Default: 2021-03-02) The version of the yaml schema file to use"); + console.log("\t--format: (Default: BASIC) The JSON Schema output format to use. Options: FLAG, BASIC, DETAILED, VERBOSE"); + process.exit(1); +} + +const args = process.argv.reduce((acc, arg) => { + if (!arg.startsWith("--")) return acc; + + const [argName, argValue] = arg.substring(2).split("=", 2); + return { ...acc, [argName]: argValue }; +}, {}); + +(async function () { + try { + // Config + JsonSchema.setMetaOutputFormat(outputFormat); + //JsonSchema.setShouldMetaValidate(false); + + const schemaType = args.schema || "schema"; + const schemaVersion = args.version || "2021-03-02"; + const ouputFormat = args.format || JsonSchema.BASIC; + + // Load schemas + JsonSchema.add(dialect); + JsonSchema.add(vocabulary); + fs.readdirSync(`${__dirname}/../schemas/v3.1`, { withFileTypes: true }) + .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) + .map((entry) => fs.readFileSync(`${__dirname}/../schemas/v3.1/${entry.name}`, "utf8")) + .map((schemaYaml) => yaml.parse(schemaYaml)) + .forEach((schema) => JsonSchema.add(schema)); + + // Compile / meta-validate + const schema = await JsonSchema.get(`https://spec.openapis.org/oas/3.1/${schemaType}/${schemaVersion}`); + const validateSchema = await JsonSchema.validate(schema); + + // Validate instance + const instanceYaml = fs.readFileSync(`${process.cwd()}/${process.argv[process.argv.length - 1]}`, "utf8"); + const instance = yaml.parse(instanceYaml); + const results = validateSchema(instance, outputFormat); + console.log(JSON.stringify(results, null, " ")); + } catch (error) { + console.log("************* Error ***************"); + console.log(error); + console.log(JSON.stringify(error.output, null, " ")); + } +}()); diff --git a/schemas/v3.1/openapi3-examples b/tests/openapi3-examples similarity index 100% rename from schemas/v3.1/openapi3-examples rename to tests/openapi3-examples diff --git a/schemas/v3.1/test.js b/tests/v3.1/test.js similarity index 76% rename from schemas/v3.1/test.js rename to tests/v3.1/test.js index 2c5bb2fd1e..77d62cb02f 100644 --- a/schemas/v3.1/test.js +++ b/tests/v3.1/test.js @@ -2,11 +2,11 @@ const fs = require("fs"); const yaml = require("yaml"); const JsonSchema = require("@hyperjump/json-schema"); const { expect } = require("chai"); -const dialect = require("./dialect/base.schema.json"); -const vocabulary = require("./meta/base.schema.json"); +const dialect = require("../../schemas/v3.1/dialect/base.schema.json"); +const vocabulary = require("../../schemas/v3.1/meta/base.schema.json"); -const testSuitePath = `${__dirname}/openapi3-examples/3.1`; +const testSuitePath = `${__dirname}/../openapi3-examples/3.1`; JsonSchema.setMetaOutputFormat(JsonSchema.BASIC); //JsonSchema.setShouldMetaValidate(false); @@ -15,9 +15,8 @@ let metaSchema; before(async () => { JsonSchema.add(dialect); JsonSchema.add(vocabulary); - JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema.yaml`, "utf8"), { prettyErrors: true })); - JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/schema-base.yaml`, "utf8"), { prettyErrors: true })); - metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema-base/2021-03-02"); + JsonSchema.add(yaml.parse(fs.readFileSync(`${__dirname}/../../schemas/v3.1/schema.yaml`, "utf8"), { prettyErrors: true })); + metaSchema = await JsonSchema.get("https://spec.openapis.org/oas/3.1/schema/2021-03-02"); }); describe("Pass", () => { From 5cde0f01efcdf26a728f90447c8c1d32193ebeec Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 11 Mar 2021 11:42:15 -0800 Subject: [PATCH 22/90] 3.1 Schema: Fixes from code review during TSC meeting --- schemas/v3.1/README.md | 4 +- schemas/v3.1/dialect/base.schema.json | 8 +--- schemas/v3.1/meta/base.schema.json | 20 ++++----- schemas/v3.1/schema.json | 59 +++++++++++++++++---------- schemas/v3.1/schema.yaml | 40 ++++++++++-------- 5 files changed, 73 insertions(+), 58 deletions(-) diff --git a/schemas/v3.1/README.md b/schemas/v3.1/README.md index 4f305d0754..01da62b56d 100644 --- a/schemas/v3.1/README.md +++ b/schemas/v3.1/README.md @@ -31,11 +31,11 @@ The TSC will then: The test suite is included as a git submodule of https://github.com/Mermade/openapi3-examples. ```bash -npx mocha --recursive [repo root]/tests +npx mocha --recursive tests ``` You can also validate a document individually. ```bash -node [repo root]/scripts/validate.js path/to/document/to/validate.yaml +scripts/validate.js path/to/document/to/validate.yaml ``` diff --git a/schemas/v3.1/dialect/base.schema.json b/schemas/v3.1/dialect/base.schema.json index 1f65d64e5d..d54b0d4d7c 100644 --- a/schemas/v3.1/dialect/base.schema.json +++ b/schemas/v3.1/dialect/base.schema.json @@ -15,13 +15,7 @@ "title": "OpenAPI 3.1 Schema Object Dialect", "allOf": [ - { "$ref": "https://json-schema.org/draft/2020-12/meta/core" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/applicator" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/unevaluated" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/validation" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/meta-data" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/format-annotation" }, - { "$ref": "https://json-schema.org/draft/2020-12/meta/content" }, + { "$ref": "https://json-schema.org/draft/2020-12/schema" }, { "$ref": "https://spec.openapis.org/oas/3.1/meta/base" } ] } diff --git a/schemas/v3.1/meta/base.schema.json b/schemas/v3.1/meta/base.schema.json index 00c127dc48..f3ee03fb96 100644 --- a/schemas/v3.1/meta/base.schema.json +++ b/schemas/v3.1/meta/base.schema.json @@ -10,18 +10,18 @@ "type": ["object", "boolean"], "properties": { "example": true, - "discriminator": { "$ref": "#/$defs/Discriminator" }, - "externalDocs": { "$ref": "#/$defs/ExternalDocs" }, - "xml": { "$ref": "#/$defs/Xml" } + "discriminator": { "$ref": "#/$defs/discriminator" }, + "externalDocs": { "$ref": "#/$defs/external-docs" }, + "xml": { "$ref": "#/$defs/xml" } }, "$defs": { - "Extensible": { + "extensible": { "patternProperties": { "^x-": true } }, - "Discriminator": { - "$ref": "#/$defs/Extensible", + "discriminator": { + "$ref": "#/$defs/extensible", "type": "object", "properties": { "propertyName": { @@ -37,8 +37,8 @@ "required": ["propertyName"], "unevaluatedProperties": false }, - "ExternalDocs": { - "$ref": "#/$defs/Extensible", + "external-docs": { + "$ref": "#/$defs/extensible", "type": "object", "properties": { "url": { @@ -52,8 +52,8 @@ "required": ["url"], "unevaluatedProperties": false }, - "Xml": { - "$ref": "#/$defs/Extensible", + "xml": { + "$ref": "#/$defs/extensible", "type": "object", "properties": { "name": { diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index a6117cfa3d..7fa4dbf6fa 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -1,15 +1,18 @@ { "$id": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", "properties": { "openapi": { - "type": "string" + "type": "string", + "pattern": "^3\\.1\\.\\d+(-.+)?$" }, "info": { "$ref": "#/$defs/info" }, "jsonSchemaDialect": { - "type": "string" + "$ref": "#/$defs/uri", + "default": "https://spec.openapis.org/oas/3.1/dialect/base" }, "servers": { "$ref": "#/$defs/server" @@ -81,7 +84,7 @@ "termsOfService": { "type": "string" }, - "contact\"": { + "contact": { "$ref": "#/$defs/contact" }, "license": { @@ -124,7 +127,7 @@ "type": "string" }, "url": { - "$ref\"": "#/$defs/uri" + "$ref": "#/$defs/uri" } }, "required": [ @@ -226,7 +229,7 @@ "headers": { "type": "object", "additionalProperties": { - "$ref\"": "#/$defs/header-or-reference" + "$ref": "#/$defs/header-or-reference" } }, "securitySchemes": { @@ -255,7 +258,8 @@ } }, "patternProperties": { - "": { + "^schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems$": { + "$comment": "Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected", "propertyNames": { "pattern": "^[a-zA-Z0-9._-]+$" } @@ -341,7 +345,7 @@ "parameters": { "type": "array", "items": { - "$ref\"": "#/$defs/parameter-or-reference" + "$ref": "#/$defs/parameter-or-reference" } }, "requestBody": { @@ -420,11 +424,32 @@ "allowEmptyValue": { "default": false, "type": "boolean" + }, + "schema": { + "$dynamicRef": "#meta" + }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + } } }, "required": [ "in" ], + "oneOf": [ + { + "required": [ + "schema" + ] + }, + { + "required": [ + "content" + ] + } + ], "dependentSchemas": { "schema": { "properties": { @@ -437,9 +462,6 @@ "allowReserved": { "default": false, "type": "boolean" - }, - "schema": { - "$dynamicRef": "#meta" } }, "allOf": [ @@ -589,16 +611,6 @@ } } } - }, - "content": { - "properties": { - "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/media-type" - } - } - } } }, "$ref": "#/$defs/specification-extensions", @@ -1003,7 +1015,10 @@ }, "schema": { "$dynamicAnchor": "meta", - "$ref": "https://spec.openapis.org/oas/3.1/dialect/base" + "type": [ + "object", + "boolean" + ] }, "security-scheme": { "type": "object", @@ -1193,7 +1208,7 @@ "$ref": "#/$defs/oauth-flows/$defs/password" }, "clientCredentials": { - "$ref\"": "#/$defs/oauth-flows/$defs/client-credentials" + "$ref": "#/$defs/oauth-flows/$defs/client-credentials" }, "authorizationCode": { "$ref": "#/$defs/oauth-flows/$defs/authorization-code" diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 3897e40429..94dcea96e5 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -1,9 +1,11 @@ $id: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' $schema: 'https://json-schema.org/draft/2020-12/schema' +type: object properties: openapi: type: string + pattern: '^3\.1\.\d+(-.+)?$' info: $ref: '#/$defs/info' jsonSchemaDialect: @@ -54,7 +56,7 @@ $defs: type: string termsOfService: type: string - contact": + contact: $ref: '#/$defs/contact' license: $ref: '#/$defs/license' @@ -86,7 +88,7 @@ $defs: identifier: type: string url: - $ref": '#/$defs/uri' + $ref: '#/$defs/uri' required: - name oneOf: @@ -156,7 +158,7 @@ $defs: headers: type: object additionalProperties: - $ref": '#/$defs/header-or-reference' + $ref: '#/$defs/header-or-reference' securitySchemes: type: object additionalProperties: @@ -174,7 +176,8 @@ $defs: additionalProperties: $ref: '#/$defs/path-item-or-reference' patternProperties: - '': + '^schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems$': + $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected propertyNames: pattern: '^[a-zA-Z0-9._-]+$' $ref: '#/$defs/specification-extensions' @@ -236,7 +239,7 @@ $defs: parameters: type: array items: - $ref": '#/$defs/parameter-or-reference' + $ref: '#/$defs/parameter-or-reference' requestBody: $ref: '#/$defs/request-body-or-reference' responses: @@ -293,8 +296,19 @@ $defs: allowEmptyValue: default: false type: boolean + schema: + $dynamicRef: '#meta' + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' required: - in + oneOf: + - required: + - schema + - required: + - content dependentSchemas: schema: properties: @@ -304,9 +318,7 @@ $defs: type: boolean allowReserved: default: false - type: "boolean" - schema: - $dynamicRef: '#meta' + type: boolean allOf: - $ref: '#/$defs/examples' - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path' @@ -397,12 +409,6 @@ $defs: explode: default: false - content: - properties: - content: - type: object - additionalProperties: - $ref: '#/$defs/media-type' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false @@ -536,9 +542,9 @@ $defs: required: - $ref then: - $ref: "#/$defs/reference" + $ref: '#/$defs/reference' else: - $ref: "#/$defs/response" + $ref: '#/$defs/response' callbacks: type: object @@ -806,7 +812,7 @@ $defs: password: $ref: '#/$defs/oauth-flows/$defs/password' clientCredentials: - $ref": '#/$defs/oauth-flows/$defs/client-credentials' + $ref: '#/$defs/oauth-flows/$defs/client-credentials' authorizationCode: $ref: '#/$defs/oauth-flows/$defs/authorization-code' $ref: '#/$defs/specification-extensions' From 84ea4a0288c967e1f7355350c946199efd963fa0 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 15 Mar 2021 10:40:48 -0700 Subject: [PATCH 23/90] 3.1 Schema: Fix anchoring in regexes --- schemas/v3.1/schema.json | 6 +++--- schemas/v3.1/schema.yaml | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index 7fa4dbf6fa..92ff85b685 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -258,7 +258,7 @@ } }, "patternProperties": { - "^schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems$": { + "^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$": { "$comment": "Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected", "propertyNames": { "pattern": "^[a-zA-Z0-9._-]+$" @@ -301,7 +301,7 @@ } }, "patternProperties": { - "^get|post|delete|options|head|patch|trace$": { + "^(get|post|delete|options|head|patch|trace)$": { "$ref": "#/$defs/operation" } }, @@ -763,7 +763,7 @@ } }, "patternProperties": { - "[1-5][0-9X]{2}": { + "^[1-5][0-9X]{2}$": { "$ref": "#/$defs/response-or-reference" } }, diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 94dcea96e5..ab73adefff 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -176,7 +176,7 @@ $defs: additionalProperties: $ref: '#/$defs/path-item-or-reference' patternProperties: - '^schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems$': + '^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$': $comment: Enumerating all of the property names in the regex above is necessary for unevaluatedProperties to work as expected propertyNames: pattern: '^[a-zA-Z0-9._-]+$' @@ -207,7 +207,7 @@ $defs: items: $ref: '#/$defs/parameter-or-reference' patternProperties: - '^get|post|delete|options|head|patch|trace$': + '^(get|post|delete|options|head|patch|trace)$': $ref: '#/$defs/operation' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false @@ -510,7 +510,7 @@ $defs: default: $ref: '#/$defs/response-or-reference' patternProperties: - '[1-5][0-9X]{2}': + '^[1-5][0-9X]{2}$': $ref: '#/$defs/response-or-reference' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false From b5bf761d9b4e9a26294ead2a2f1a2e7d99bcd85d Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Fri, 19 Mar 2021 15:30:03 -0700 Subject: [PATCH 24/90] 3.1 Schema: Add media-range format for content objects --- schemas/v3.1/schema.json | 32 +++++++++++++++----------------- schemas/v3.1/schema.yaml | 24 ++++++++++++------------ 2 files changed, 27 insertions(+), 29 deletions(-) diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index 92ff85b685..fa987c12d6 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -429,10 +429,7 @@ "$dynamicRef": "#meta" }, "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/media-type" - } + "$ref": "#/$defs/content" } }, "required": [ @@ -636,10 +633,7 @@ "type": "string" }, "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/media-type" - } + "$ref": "#/$defs/content" }, "required": { "default": false, @@ -665,6 +659,15 @@ "$ref": "#/$defs/request-body" } }, + "content": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/media-type" + }, + "propertyNames": { + "format": "media-range" + } + }, "media-type": { "type": "object", "properties": { @@ -692,7 +695,8 @@ "type": "object", "properties": { "contentType": { - "type": "string" + "type": "string", + "format": "media-range" }, "headers": { "type": "object", @@ -783,10 +787,7 @@ } }, "content": { - "type": "object", - "addtionalProperties": { - "$ref": "#/$defs/media-type" - } + "$ref": "#/$defs/content" }, "links": { "type": "object", @@ -955,10 +956,7 @@ "content": { "properties": { "content": { - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/media-type" - } + "$ref": "#/$defs/content" } } } diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index ab73adefff..9b71e11031 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -299,9 +299,7 @@ $defs: schema: $dynamicRef: '#meta' content: - type: object - additionalProperties: - $ref: '#/$defs/media-type' + $ref: '#/$defs/content' required: - in oneOf: @@ -427,9 +425,7 @@ $defs: description: type: string content: - type: object - additionalProperties: - $ref: '#/$defs/media-type' + $ref: '#/$defs/content' required: default: false type: boolean @@ -447,6 +443,13 @@ $defs: else: $ref: '#/$defs/request-body' + content: + type: object + additionalProperties: + $ref: '#/$defs/media-type' + propertyNames: + format: media-range + media-type: type: object properties: @@ -466,6 +469,7 @@ $defs: properties: contentType: type: string + format: media-range headers: type: object additionalProperties: @@ -525,9 +529,7 @@ $defs: additionalProperties: $ref: '#/$defs/header-or-reference' content: - type: object - addtionalProperties: - $ref: '#/$defs/media-type' + $ref: '#/$defs/content' links: type: object additionalProperties: @@ -646,9 +648,7 @@ $defs: content: properties: content: - type: object - additionalProperties: - $ref: '#/$defs/media-type' + $ref: '#/$defs/content' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false From 1ce46a056a766aeee05b53a6a631073b7ef18e8c Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Fri, 19 Mar 2021 21:59:50 -0700 Subject: [PATCH 25/90] 3.1 Schema: Remove submodule --- .gitmodules | 3 -- scripts/validate.js | 8 +-- tests/openapi3-examples | 1 - tests/v3.1/fail/no_containers.yaml | 4 ++ tests/v3.1/fail/sever_enum_empty.yaml | 11 ++++ tests/v3.1/fail/sever_enum_unknown.yaml | 12 +++++ tests/v3.1/fail/unknown_container.yaml | 5 ++ tests/v3.1/pass/comp_pathitems.yaml | 6 +++ tests/v3.1/pass/info_summary.yaml | 6 +++ tests/v3.1/pass/license_identifier.yaml | 9 ++++ tests/v3.1/pass/mega.yaml | 49 +++++++++++++++++ tests/v3.1/pass/minimal_comp.yaml | 5 ++ tests/v3.1/pass/minimal_hooks.yaml | 5 ++ tests/v3.1/pass/minimal_paths.yaml | 5 ++ tests/v3.1/pass/path_no_response.yaml | 7 +++ tests/v3.1/pass/path_var_empty_pathitem.yaml | 6 +++ tests/v3.1/pass/schema.yaml | 55 ++++++++++++++++++++ tests/v3.1/test.js | 10 ++-- 18 files changed, 193 insertions(+), 14 deletions(-) delete mode 160000 tests/openapi3-examples create mode 100644 tests/v3.1/fail/no_containers.yaml create mode 100644 tests/v3.1/fail/sever_enum_empty.yaml create mode 100644 tests/v3.1/fail/sever_enum_unknown.yaml create mode 100644 tests/v3.1/fail/unknown_container.yaml create mode 100644 tests/v3.1/pass/comp_pathitems.yaml create mode 100644 tests/v3.1/pass/info_summary.yaml create mode 100644 tests/v3.1/pass/license_identifier.yaml create mode 100644 tests/v3.1/pass/mega.yaml create mode 100644 tests/v3.1/pass/minimal_comp.yaml create mode 100644 tests/v3.1/pass/minimal_hooks.yaml create mode 100644 tests/v3.1/pass/minimal_paths.yaml create mode 100644 tests/v3.1/pass/path_no_response.yaml create mode 100644 tests/v3.1/pass/path_var_empty_pathitem.yaml create mode 100644 tests/v3.1/pass/schema.yaml diff --git a/.gitmodules b/.gitmodules index ca8320435d..e69de29bb2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +0,0 @@ -[submodule "tests/v3.1/openapi3-examples"] - path = tests/openapi3-examples - url = git@github.com:Mermade/openapi3-examples.git diff --git a/scripts/validate.js b/scripts/validate.js index cf1c2d09ca..c9c70db797 100755 --- a/scripts/validate.js +++ b/scripts/validate.js @@ -24,14 +24,14 @@ const args = process.argv.reduce((acc, arg) => { (async function () { try { + const schemaType = args.schema || "schema"; + const schemaVersion = args.version || "2021-03-02"; + const outputFormat = args.format || JsonSchema.BASIC; + // Config JsonSchema.setMetaOutputFormat(outputFormat); //JsonSchema.setShouldMetaValidate(false); - const schemaType = args.schema || "schema"; - const schemaVersion = args.version || "2021-03-02"; - const ouputFormat = args.format || JsonSchema.BASIC; - // Load schemas JsonSchema.add(dialect); JsonSchema.add(vocabulary); diff --git a/tests/openapi3-examples b/tests/openapi3-examples deleted file mode 160000 index 9c2997e1a2..0000000000 --- a/tests/openapi3-examples +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 9c2997e1a25919a8182080cc43a4db06d2dc775d diff --git a/tests/v3.1/fail/no_containers.yaml b/tests/v3.1/fail/no_containers.yaml new file mode 100644 index 0000000000..6cc86aae92 --- /dev/null +++ b/tests/v3.1/fail/no_containers.yaml @@ -0,0 +1,4 @@ +iopenapi: 3.1.0 +info: + title: API + version: 1.0.0 diff --git a/tests/v3.1/fail/sever_enum_empty.yaml b/tests/v3.1/fail/sever_enum_empty.yaml new file mode 100644 index 0000000000..62d751e171 --- /dev/null +++ b/tests/v3.1/fail/sever_enum_empty.yaml @@ -0,0 +1,11 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +servers: + - url: https://example.com/{var} + variables: + var: + enum: [] + default: a +components: {} diff --git a/tests/v3.1/fail/sever_enum_unknown.yaml b/tests/v3.1/fail/sever_enum_unknown.yaml new file mode 100644 index 0000000000..eb8c8f6872 --- /dev/null +++ b/tests/v3.1/fail/sever_enum_unknown.yaml @@ -0,0 +1,12 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +servers: + - url: https://example.com/{var} + variables: + var: + enum: + - a + default: b +components: {} diff --git a/tests/v3.1/fail/unknown_container.yaml b/tests/v3.1/fail/unknown_container.yaml new file mode 100644 index 0000000000..e0565f4a5a --- /dev/null +++ b/tests/v3.1/fail/unknown_container.yaml @@ -0,0 +1,5 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +overlays: {} diff --git a/tests/v3.1/pass/comp_pathitems.yaml b/tests/v3.1/pass/comp_pathitems.yaml new file mode 100644 index 0000000000..502ca1fca2 --- /dev/null +++ b/tests/v3.1/pass/comp_pathitems.yaml @@ -0,0 +1,6 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +components: + pathItems: {} diff --git a/tests/v3.1/pass/info_summary.yaml b/tests/v3.1/pass/info_summary.yaml new file mode 100644 index 0000000000..30d224afc2 --- /dev/null +++ b/tests/v3.1/pass/info_summary.yaml @@ -0,0 +1,6 @@ +openapi: 3.1.0 +info: + title: API + summary: My lovely API + version: 1.0.0 +components: {} diff --git a/tests/v3.1/pass/license_identifier.yaml b/tests/v3.1/pass/license_identifier.yaml new file mode 100644 index 0000000000..fbdba5efbe --- /dev/null +++ b/tests/v3.1/pass/license_identifier.yaml @@ -0,0 +1,9 @@ +openapi: 3.1.0 +info: + title: API + summary: My lovely API + version: 1.0.0 + license: + name: Apache + identifier: Apache-2.0 +components: {} diff --git a/tests/v3.1/pass/mega.yaml b/tests/v3.1/pass/mega.yaml new file mode 100644 index 0000000000..8838c03a6d --- /dev/null +++ b/tests/v3.1/pass/mega.yaml @@ -0,0 +1,49 @@ +openapi: 3.1.0 +info: + summary: My API's summary + title: My API + version: 1.0.0 + license: + name: Apache 2.0 + identifier: Apache-2.0 +jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base +paths: + /: + get: + parameters: [] + /{pathTest}: {} +webhooks: + myWebhook: + $ref: '#/components/pathItems/myPathItem' + description: Overriding description +components: + securitySchemes: + mtls: + type: mutualTLS + pathItems: + myPathItem: + post: + requestBody: + required: true + content: + 'application/json': + schema: + type: object + properties: + type: + type: string + int: + type: integer + exclusiveMaximum: 100 + exclusiveMinimum: 0 + none: + type: 'null' + arr: + type: array + $comment: Array without items keyword + either: + type: ['string','null'] + discriminator: + propertyName: type + x-extension: true + myArbitraryKeyword: true diff --git a/tests/v3.1/pass/minimal_comp.yaml b/tests/v3.1/pass/minimal_comp.yaml new file mode 100644 index 0000000000..4553689ab4 --- /dev/null +++ b/tests/v3.1/pass/minimal_comp.yaml @@ -0,0 +1,5 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +components: {} diff --git a/tests/v3.1/pass/minimal_hooks.yaml b/tests/v3.1/pass/minimal_hooks.yaml new file mode 100644 index 0000000000..e67b2889de --- /dev/null +++ b/tests/v3.1/pass/minimal_hooks.yaml @@ -0,0 +1,5 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +webhooks: {} diff --git a/tests/v3.1/pass/minimal_paths.yaml b/tests/v3.1/pass/minimal_paths.yaml new file mode 100644 index 0000000000..016e86796f --- /dev/null +++ b/tests/v3.1/pass/minimal_paths.yaml @@ -0,0 +1,5 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} diff --git a/tests/v3.1/pass/path_no_response.yaml b/tests/v3.1/pass/path_no_response.yaml new file mode 100644 index 0000000000..334608f111 --- /dev/null +++ b/tests/v3.1/pass/path_no_response.yaml @@ -0,0 +1,7 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: + /: + get: {} diff --git a/tests/v3.1/pass/path_var_empty_pathitem.yaml b/tests/v3.1/pass/path_var_empty_pathitem.yaml new file mode 100644 index 0000000000..ba92742f10 --- /dev/null +++ b/tests/v3.1/pass/path_var_empty_pathitem.yaml @@ -0,0 +1,6 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: + /{var}: {} diff --git a/tests/v3.1/pass/schema.yaml b/tests/v3.1/pass/schema.yaml new file mode 100644 index 0000000000..e192529a68 --- /dev/null +++ b/tests/v3.1/pass/schema.yaml @@ -0,0 +1,55 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} +components: + schemas: + model: + type: object + properties: + one: + description: type array + type: + - integer + - string + two: + description: type 'null' + type: "null" + three: + description: type array including 'null' + type: + - string + - "null" + four: + description: array with no items + type: array + five: + description: singular example + type: string + examples: + - exampleValue + six: + description: exclusiveMinimum true + exclusiveMinimum: 10 + seven: + description: exclusiveMinimum false + minimum: 10 + eight: + description: exclusiveMaximum true + exclusiveMaximum: 20 + nine: + description: exclusiveMaximum false + maximum: 20 + ten: + description: nullable string + type: + - string + - "null" + eleven: + description: x-nullable string + type: + - string + - "null" + twelve: + description: file/binary diff --git a/tests/v3.1/test.js b/tests/v3.1/test.js index 77d62cb02f..43f7e80588 100644 --- a/tests/v3.1/test.js +++ b/tests/v3.1/test.js @@ -6,8 +6,6 @@ const dialect = require("../../schemas/v3.1/dialect/base.schema.json"); const vocabulary = require("../../schemas/v3.1/meta/base.schema.json"); -const testSuitePath = `${__dirname}/../openapi3-examples/3.1`; - JsonSchema.setMetaOutputFormat(JsonSchema.BASIC); //JsonSchema.setShouldMetaValidate(false); @@ -20,10 +18,10 @@ before(async () => { }); describe("Pass", () => { - fs.readdirSync(`${testSuitePath}/pass`, { withFileTypes: true }) + fs.readdirSync(`${__dirname}/pass`, { withFileTypes: true }) .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) .forEach((entry) => { - const file = `${testSuitePath}/pass/${entry.name}`; + const file = `${__dirname}/pass/${entry.name}`; it(entry.name, async () => { const instance = yaml.parse(fs.readFileSync(file, "utf8")); @@ -35,10 +33,10 @@ describe("Pass", () => { }); describe("Fail", () => { - fs.readdirSync(`${testSuitePath}/fail`, { withFileTypes: true }) + fs.readdirSync(`${__dirname}/fail`, { withFileTypes: true }) .filter((entry) => entry.isFile() && /\.yaml$/.test(entry.name)) .forEach((entry) => { - const file = `${testSuitePath}/fail/${entry.name}`; + const file = `${__dirname}/fail/${entry.name}`; it(entry.name, async () => { const instance = yaml.parse(fs.readFileSync(file, "utf8")); From 6e5b27a191c1cba9b3f61e7bf9b031fa75a0157f Mon Sep 17 00:00:00 2001 From: Darrel Date: Thu, 1 Apr 2021 12:19:13 -0400 Subject: [PATCH 26/90] Updated Overlay proposal (#2300) * Updated Overlay proposal * fixed examples * Update proposals/004_Overlays.md Co-authored-by: Mike Ralphson Co-authored-by: Mike Ralphson --- proposals/004_Overlays.md | 27 ++++++------ proposals/Overlays/Changes.yml | 70 +++++++++++++++++++++++++++++++ proposals/Overlays/MergePatch.yml | 10 +++++ 3 files changed, 94 insertions(+), 13 deletions(-) create mode 100644 proposals/Overlays/Changes.yml create mode 100644 proposals/Overlays/MergePatch.yml diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md index 77e7128db1..05fce28797 100644 --- a/proposals/004_Overlays.md +++ b/proposals/004_Overlays.md @@ -15,12 +15,12 @@ |---- | ---------------- | ---------- | | 24th December 2019 | Darrel Miller | Initial draft | | 2nd January 2019 | Darrel Miller | Update to wording around removing items from arrays. Added section on backward compatibility. Clarified process around applying a set of updates. Started to add supported scenarios.| +| 29th July 2020 | Darrel Miller | Updated to be explicit about update operations | ## Introduction In recent months we have been discussing various use cases for overlays and various solutions. The following proposal takes a somewhat more radical approach to the problem. It is a more ambitious proposal than the others we have seen before but the additional complexity does allow for supporting many of the scenarios that have been discussed to date. - #### Overlay Document An overlay document contains a list of [Update Objects](#overlayUpdates) that are to be applied to the target document. Each [Update Object](#updateObject) has a `target` property and a `value` property. The `target` property is a [JMESPath](http://jmespath.org/specification.html) query that identifies what part of the target document is to be updated and the `value` property contains an object with the properties to be overlaid. @@ -63,10 +63,11 @@ This object represents one or more changes to be applied to the target document 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`. +add | [Any](#addObject) | An object to be added as a child of the object(s) referenced by the target. Property has no impact if `remove` property is `true`. +merge | [Any](#mergeObject) | An object with the properties and values to be merged with the object(s) referenced by the target. Property has no impact if `remove` property is `true`. remove | `boolean` | A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false. -The properties of the `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. +The properties of the merge object MUST be compatible with the target object referenced by the JMESPath key. When the Overlay document is applied, the properties in the merge object replace properties in the target object with the same name and new properties are appended to the target object. ##### Structured Overlays Example @@ -79,7 +80,7 @@ info: version: 1.0.0 updates: - target: "@" - value: + merge: info: x-overlay-applied: structured-overlay paths: @@ -103,17 +104,17 @@ Alternatively, where only a small number of updates need to be applied to a larg ```yaml overlay: 1.0.0 info: - title: Structured Overlay + title: Targeted Overlays version: 1.0.0 updates: - target: paths."/foo".get - value: + merge: description: This is the new description - target: paths."/bar".get - value: + merge: description: This is the updated description - target: paths."/bar" - value: + merge: post: description: This is an updated description of a child object x-safe: false @@ -130,10 +131,10 @@ info: version: 1.0.0 updates: - target: paths.*.get - value: + merge: x-safe: true - target: paths.*.get.parameters[?name=='filter' && in=='query'] - value: + merge: schema: $ref: "/components/schemas/filterSchema" ``` @@ -148,8 +149,8 @@ info: title: Add an array element version: 1.0.0 updates: -- target: paths.*.get.parameters[length(@)] - value: +- target: paths.*.get.parameters + add: name: newParam in: query ``` @@ -160,7 +161,7 @@ info: title: Remove a array element version: 1.0.0 updates: -- target: $.paths[*].get.parameters[? name == 'dummy'] +- target: paths[*].get.parameters[? name == 'dummy'] remove: true ``` diff --git a/proposals/Overlays/Changes.yml b/proposals/Overlays/Changes.yml new file mode 100644 index 0000000000..d2abf79e64 --- /dev/null +++ b/proposals/Overlays/Changes.yml @@ -0,0 +1,70 @@ +# Create update methods (add,replace,merge,delete)? Is merge necessary? +# Multiple additions or updates to the same target is more efficient with merge + +# Different than JSON Patch because is works in JSON and YAML +# Has info object and spec version +# values + +overlay: 1.0.0 +info: + title: An example of an overlay that captures changes to an API + version: 1.0.0 +updates: +# Add a property to a schema +- target: components.schemas."todo".properties + merge: + createdBy: + type: string +# Add constraints to a schema +- target: components.schemas."todo" + merge: + additionalProperties: false +- target: components.schemas."todo" + merge: + type: ["object","null"] +#Change a schema +- target: components.schemas."todo" + replace: + type: integer +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] +# Add multiple constraints to a schema using merge +- target: components.schemas."todo" + merge: + additionalProperties: false + type: ["object","null"] + properties: + someprop: + type: string +# Add an operation +- target: paths."/foo" + add: + delete: + description: delete a foo + responses: + 200: + description: ok +# Add a path +- target: paths + add: + "/items": + get: + responses: + 200: + description: ok +# Add an optional query parameter +- target: paths."/bar".parameters + add: + name: skip + in: query + type: string +# Mark an operation as deprecated + +# Change the value of a JSON schema constraint +# Update the version of the API +# Change the license of an API +# Add support for a new request media type +# Add support for a new response media type diff --git a/proposals/Overlays/MergePatch.yml b/proposals/Overlays/MergePatch.yml new file mode 100644 index 0000000000..3bd4d0a1cb --- /dev/null +++ b/proposals/Overlays/MergePatch.yml @@ -0,0 +1,10 @@ +overlay: 1.0.0 +info: + title: An example of an overlay that performs a Merge Patch + version: 1.0.0 +updates: +- target: "@" + merge: + openapi: 3.0.3 + paths: {} + From 14c0908becbccd78252be49bd92be8c53cd2b9e3 Mon Sep 17 00:00:00 2001 From: Darrel Date: Mon, 12 Apr 2021 12:25:49 -0400 Subject: [PATCH 27/90] Added example of making overlays work like traits (#2534) --- proposals/004_Overlays.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md index 05fce28797..de820558ba 100644 --- a/proposals/004_Overlays.md +++ b/proposals/004_Overlays.md @@ -165,6 +165,43 @@ updates: remove: true ``` +##### Traits Examples + +By annotating an OpenAPI description using extension such as `x-oai-traits` an author of OpenAPI description can identify where overlay updates should be applied. + +```yaml +openapi: 3.1.0 +info: + title: Api with a paged collection + version: 1.0.0 +paths: + /items: + get: + x-oai-traits: ["paged"] + responses: + 200: + description: OK +``` + +With the above OpenAPI description, following Overlay document will apply the necessary updates to describe how paging is implemented, where that trait has been applied. + +```yaml +overlay: 1.0.0 +info: + title: Apply Traits + version: 1.0.0 +updates: +- target: $.paths[*].get[?contains(x-traits,'paged')] + merge: + parameters: + - name: top + in: query + - name: skip + in: query +``` + +This approach allows flipping control of where Overlays apply updates to the OpenAPI description itself. + ## Proposal Summary ### Benefits From 54b0264dbdb018f3f1166872c73a0d5bd6786d27 Mon Sep 17 00:00:00 2001 From: Sami Akkawi <45228655+SamiAkkawi@users.noreply.github.com> Date: Thu, 15 Apr 2021 19:02:49 +0200 Subject: [PATCH 28/90] servers is an array of server (#2526) * servers is an array of server * fix only yaml file * add servers test * update schema.json from shema.yaml --- schemas/v3.1/schema.json | 7 +++++-- schemas/v3.1/schema.yaml | 4 +++- tests/v3.1/fail/servers.yaml | 8 ++++++++ tests/v3.1/pass/servers.yaml | 10 ++++++++++ 4 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 tests/v3.1/fail/servers.yaml create mode 100644 tests/v3.1/pass/servers.yaml diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index fa987c12d6..e1e859dbe3 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -15,7 +15,10 @@ "default": "https://spec.openapis.org/oas/3.1/dialect/base" }, "servers": { - "$ref": "#/$defs/server" + "type": "array", + "items": { + "$ref": "#/$defs/server" + } }, "paths": { "$ref": "#/$defs/paths" @@ -1337,4 +1340,4 @@ } } } -} +} \ No newline at end of file diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 9b71e11031..60377ae424 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -12,7 +12,9 @@ properties: $ref: '#/$defs/uri' default: 'https://spec.openapis.org/oas/3.1/dialect/base' servers: - $ref: '#/$defs/server' + type: array + items: + $ref: '#/$defs/server' paths: $ref: '#/$defs/paths' webhooks: diff --git a/tests/v3.1/fail/servers.yaml b/tests/v3.1/fail/servers.yaml new file mode 100644 index 0000000000..7aaa05c0af --- /dev/null +++ b/tests/v3.1/fail/servers.yaml @@ -0,0 +1,8 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} +servers: + url: /v1 + description: Run locally. diff --git a/tests/v3.1/pass/servers.yaml b/tests/v3.1/pass/servers.yaml new file mode 100644 index 0000000000..77a20498da --- /dev/null +++ b/tests/v3.1/pass/servers.yaml @@ -0,0 +1,10 @@ +openapi: 3.1.0 +info: + title: API + version: 1.0.0 +paths: {} +servers: + - url: /v1 + description: Run locally. + - url: https://production.com/v1 + description: Run on production server. From 9092530007cbc8edabd121523061eba9d62b7716 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Wed, 7 Apr 2021 12:14:19 -0700 Subject: [PATCH 29/90] Add "put" to allowed property name for PathItem in 3.1 schema --- schemas/v3.1/schema.json | 4 ++-- schemas/v3.1/schema.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index e1e859dbe3..fc6ff147a7 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -304,7 +304,7 @@ } }, "patternProperties": { - "^(get|post|delete|options|head|patch|trace)$": { + "^(get|put|post|delete|options|head|patch|trace)$": { "$ref": "#/$defs/operation" } }, @@ -1340,4 +1340,4 @@ } } } -} \ No newline at end of file +} diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index 60377ae424..a4c1e7e109 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -209,7 +209,7 @@ $defs: items: $ref: '#/$defs/parameter-or-reference' patternProperties: - '^(get|post|delete|options|head|patch|trace)$': + '^(get|put|post|delete|options|head|patch|trace)$': $ref: '#/$defs/operation' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false From 08d22f6f712fcc79f819bd5cb3fb394b89cfddce Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 15 Apr 2021 09:32:07 -0700 Subject: [PATCH 30/90] Update $id for release --- schemas/v3.1/schema-base.json | 4 ++-- schemas/v3.1/schema-base.yaml | 4 ++-- schemas/v3.1/schema.json | 2 +- schemas/v3.1/schema.yaml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/schemas/v3.1/schema-base.json b/schemas/v3.1/schema-base.json index 078af184fe..658e943cc5 100644 --- a/schemas/v3.1/schema-base.json +++ b/schemas/v3.1/schema-base.json @@ -1,7 +1,7 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema-base/2021-04-15", "$schema": "https://json-schema.org/draft/2020-12/schema", - "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$ref": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", "properties": { "jsonSchemaDialect": { "$ref": "#/$defs/dialect" diff --git a/schemas/v3.1/schema-base.yaml b/schemas/v3.1/schema-base.yaml index 41a27be7a9..515ed08989 100644 --- a/schemas/v3.1/schema-base.yaml +++ b/schemas/v3.1/schema-base.yaml @@ -1,7 +1,7 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema-base/2021-04-15' $schema: 'https://json-schema.org/draft/2020-12/schema' -$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$ref: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' properties: jsonSchemaDialect: $ref: '#/$defs/dialect' diff --git a/schemas/v3.1/schema.json b/schemas/v3.1/schema.json index fc6ff147a7..a798834247 100644 --- a/schemas/v3.1/schema.json +++ b/schemas/v3.1/schema.json @@ -1,5 +1,5 @@ { - "$id": "https://spec.openapis.org/oas/3.1/schema/2021-03-02", + "$id": "https://spec.openapis.org/oas/3.1/schema/2021-04-15", "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { diff --git a/schemas/v3.1/schema.yaml b/schemas/v3.1/schema.yaml index a4c1e7e109..86cb44efca 100644 --- a/schemas/v3.1/schema.yaml +++ b/schemas/v3.1/schema.yaml @@ -1,4 +1,4 @@ -$id: 'https://spec.openapis.org/oas/3.1/schema/2021-03-02' +$id: 'https://spec.openapis.org/oas/3.1/schema/2021-04-15' $schema: 'https://json-schema.org/draft/2020-12/schema' type: object From 5b55a134bcf7aa50b9e54704d3df979e17f25d19 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Sun, 18 Apr 2021 17:20:14 +0100 Subject: [PATCH 31/90] fix: update refs to master branch to main (#2546) Signed-off-by: Mike Ralphson --- .github/workflows/convert-examples-to-json.yaml | 9 ++++----- .github/workflows/validate-markdown.yaml | 2 +- DEVELOPMENT.md | 8 ++++---- README.md | 4 ++-- guidelines/v2.0/REUSE.md | 6 +++--- proposals/000_OAS-proposal-template.md | 4 ++-- proposals/001_Alternative Schema Proposal.md | 10 +++++----- proposals/002_Webhooks.md | 2 +- proposals/003_Clarify-Nullable.md | 2 +- proposals/004_Overlays.md | 2 +- proposals/Alternative Schema/schema_object.md | 6 +++--- 11 files changed, 27 insertions(+), 28 deletions(-) diff --git a/.github/workflows/convert-examples-to-json.yaml b/.github/workflows/convert-examples-to-json.yaml index 2ed4ca865e..8cc63f5398 100644 --- a/.github/workflows/convert-examples-to-json.yaml +++ b/.github/workflows/convert-examples-to-json.yaml @@ -10,11 +10,11 @@ name: convert-examples-to-json # Only the YAML files should be adjusted manually. # -# run this on push to master +# run this on push to main on: push: branches: - - master + - main jobs: yaml2json: @@ -22,7 +22,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 # checkout repo content + - uses: actions/checkout@v2 # checkout repo content - name: Install dependencies run: npm i @@ -36,10 +36,9 @@ jobs: git --no-pager -c color.diff=always diff --staged - name: Create Pull Request - uses: peter-evans/create-pull-request@v1 + uses: peter-evans/create-pull-request@v3 with: token: ${{ secrets.GITHUB_TOKEN }} - branch-suffix: none branch: update-json-examples title: Update JSON example files commit-message: Update JSON example files diff --git a/.github/workflows/validate-markdown.yaml b/.github/workflows/validate-markdown.yaml index a127677452..05af39ceaf 100644 --- a/.github/workflows/validate-markdown.yaml +++ b/.github/workflows/validate-markdown.yaml @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 # checkout repo content + - uses: actions/checkout@v2 # checkout repo content - uses: actions/setup-node@v1 # setup Node.js with: node-version: '12.x' diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8a768b3d1c..6b8fc56e87 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -40,7 +40,7 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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. + * main - 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. @@ -48,7 +48,7 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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. +* The main branch shall remain the current, released OpenAPI Specification. We will describe and link the work branch(es) on the **default** README.md on main. * Examples of how something is described *currently* vs. the proposed solution should accompany any change proposal. @@ -62,11 +62,11 @@ Spec changes should be approved by a majority of the committers. Approval can be * 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. +* When the work branch is ready and approved, the branch will be merged to main. ## 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. +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 main with marketing support, if any. * Patch-level releases require majority approval by TSC members. (Max voting period 3 days) diff --git a/README.md b/README.md index 0a81ca7f21..9c399250a5 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot 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. +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 `main`. 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). @@ -53,6 +53,6 @@ Not all feedback can be accommodated and there may be solid arguments for or aga ## Licensing -See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/master/LICENSE) +See: [License (Apache-2.0)](https://github.com/OAI/OpenAPI-Specification/blob/main/LICENSE) ![Analytics](https://ga-beacon.appspot.com/UA-831873-42/readme.md?pixel) diff --git a/guidelines/v2.0/REUSE.md b/guidelines/v2.0/REUSE.md index 2d3192c262..60975c484a 100644 --- a/guidelines/v2.0/REUSE.md +++ b/guidelines/v2.0/REUSE.md @@ -81,7 +81,7 @@ When referencing locally (within the current document), the target references sh An example of a local definition reference: -_Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_ +_Example from https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v2.0/json/petstore.json_ ``` json // ... "200": { @@ -100,7 +100,7 @@ _Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/ 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_ +_Example from https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... @@ -116,7 +116,7 @@ _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/ 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_ +_Example from https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v2.0/json/petstore-separate/spec/swagger.json_ ``` json // ... "parameters": [ diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md index da2a8b1eeb..799c73b491 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/000_OAS-proposal-template.md @@ -5,11 +5,11 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})| +|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/main/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)| +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/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}) | diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 9f176ea28e..a0faab8c06 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -4,11 +4,11 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| +|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/main/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) +|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/main/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) | @@ -42,14 +42,14 @@ This proposal makes the following changes to the OAS 3.0 specification: ### 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) +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/main/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) +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/main/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) +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/main/proposals/Alternative%20Schema/alternative_schema_examples.md) ### Alternative Schema Registry diff --git a/proposals/002_Webhooks.md b/proposals/002_Webhooks.md index 8ad8a97fa9..3daf5aadff 100644 --- a/proposals/002_Webhooks.md +++ b/proposals/002_Webhooks.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)| +|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/002_webhooks.md)| |Authors|[Lorna Mitchell](https://github.com/lornajane)| |Review Manager |TBD | |Status |Proposal| diff --git a/proposals/003_Clarify-Nullable.md b/proposals/003_Clarify-Nullable.md index 139b0dceef..7e82c7b6ca 100644 --- a/proposals/003_Clarify-Nullable.md +++ b/proposals/003_Clarify-Nullable.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/003_Clarify-Nullable.md)| +|Proposal |[003](https://github.com/OAI/OpenAPI-Specification/tree/main/proposals/003_Clarify-Nullable.md)| |Authors|[Ted Epstein](https://github.com/tedepstein)| |Review Manager |TBD| |Status |Proposal| diff --git a/proposals/004_Overlays.md b/proposals/004_Overlays.md index de820558ba..4c352804c0 100644 --- a/proposals/004_Overlays.md +++ b/proposals/004_Overlays.md @@ -4,7 +4,7 @@ |Tag |Value | |---- | ---------------- | -|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/004_overlays.md)| +|Proposal |[004_Overlays](https://github.com/OAI/OpenAPI-Specification/tree/main/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)| diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md index df8c64c8ff..7d9f57ecdd 100644 --- a/proposals/Alternative Schema/schema_object.md +++ b/proposals/Alternative Schema/schema_object.md @@ -7,11 +7,11 @@ The following content shall be used to replace the Fixed Fields table in the Sch |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. | +| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/main/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/main/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. +| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/main/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/main/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. | From 912498eba3a559e74bb546b04d687e8e46d59c86 Mon Sep 17 00:00:00 2001 From: Neal Caidin Date: Mon, 26 Apr 2021 10:20:09 -0400 Subject: [PATCH 32/90] Update TOB.md The election cycle for 2021 is complete and the existing TSC-elected members have agreed to serve another term. No additional nominations were received. --- TOB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOB.md b/TOB.md index 0a6f6f2868..c40deee81d 100644 --- a/TOB.md +++ b/TOB.md @@ -3,7 +3,7 @@ ## 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 +## TSC Elected - terms through May 2023 Isabelle Mauny @isamauny Uri Sarid @usarid From a295d9af0e64ba9b9d0cbbc2c6f63f1bf2e967d5 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 20 May 2021 17:38:59 +0100 Subject: [PATCH 33/90] feat: add agenda workflow/template (#2571) Signed-off-by: Mike Ralphson --- .github/templates/agenda.md | 19 +++++++++++++++++++ .github/workflows/agenda.yaml | 29 +++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 .github/templates/agenda.md create mode 100644 .github/workflows/agenda.yaml diff --git a/.github/templates/agenda.md b/.github/templates/agenda.md new file mode 100644 index 0000000000..590983c7ef --- /dev/null +++ b/.github/templates/agenda.md @@ -0,0 +1,19 @@ +**NOTE: This meeting is on Thursday at 9am - 10am PT** + +Zoom Meeting link: [https://zoom.us/j/975841675](https://zoom.us/j/975841675?pwd=SUh4MjRLaEFKNlI3RElpWTdhRDVVUT09). Dial-in passcode: 763054 + +In order to give some more visibility into the topics we cover in the TDC meetings here is the planned agenda for the next meeting. Hopefully this will allow people to plan to attend meetings for topics that they have an interest in. And for folks who cannot attend they can comment on this issue prior to the meeting. Feel free to suggest other potential agenda topics. + +**Please submit comments below for topics or proposals that you wish to present in the TDC meeting** + +The agenda backlog is currently maintained in issue #2482 + +| Topic | Owner | Decision/NextStep | +|-------|---------|---------| +| | | | +AOB (see below) | TDC | | +New issues / PRs labelled [review](https://github.com/OAI/OpenAPI-Specification/labels/review) | @OAI/triage | | +[New issues](https://github.com/search?q=repo%3Aoai%2Fopenapi-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) without response yet | @OAI/triage | | + + +/cc @OAI/tsc Please suggest items for inclusion diff --git a/.github/workflows/agenda.yaml b/.github/workflows/agenda.yaml new file mode 100644 index 0000000000..d9c347ef31 --- /dev/null +++ b/.github/workflows/agenda.yaml @@ -0,0 +1,29 @@ +name: agenda + +# author: @MikeRalphson +# issue: various + +# +# This workflow creates the agenda issue each week. It runs on a cron every +# Monday morning, raising an issue for the following Thursday. +# It can also be run manually, in case GitHub Actions has a failure. +# + +on: + schedule: + - cron: '0 9 * * 2' + workflow_dispatch: {} + +jobs: + agenda: + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v1 # checkout repo content + + - name: Create agenda issue + run: gh issue create -l Housekeeping -t "Open Community (TDC) Meeting, `date --date='next Thu' +'%A %d %B %Y'`" -F .github/templates/agenda.md + From cc45c37d69048993db05e03a28fb7331c0697ad5 Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 20 May 2021 17:42:25 +0100 Subject: [PATCH 34/90] Add script and GitHub action to automatically generate ReSpec versions of the spec (#2574) * workflows: update used actions * . * bikeshed rendering (WIP) * bikeshed; split into v2, v3 directories * bikeshed; fixes to TOC,code blocks and indent levels * bikeshed; work from unmodified .md files * bikeshed; .gitignore * bikeshed; separate header for v3.0.1 for now * respec; as an alternative to bikeshed * Rename bikeshed to md2html * md2html; current setup * md2html; wip * md2html; fix 1 toc bug * md2html; fix another toc bug * md2html; fix 1 respec toc bug * md2html; fix another bikeshed toc bug * respec; former editor support - needs ReSpec 20.x * Latest respec tweaks * pre block css background, RFC ref fixes * Github gist syntax highlighting css * md2html: move to scripts dir * md2html: resolve relative links for examples * md2html: use respec js from spec.openapis.org site * md2html: find gist.css regardless of run dir * md2html: don't mix https and http content (toc) * md2html; include google analytics * md2html; build putative versions 4,5 etc * md2html; tidying up * md2html; specify lang="en" in html * build: update deps * fix: style examples bugs, refs #2488 * fix: update highlightjs call in md2html * feat: add github action Signed-off-by: Mike Ralphson * build: create a `latest.html` ReSpec version Signed-off-by: Mike Ralphson --- .github/workflows/respec.yaml | 55 +++++ .gitignore | 2 + package.json | 7 +- scripts/md2html/.gitignore | 2 + scripts/md2html/analytics/google.html | 8 + scripts/md2html/build.sh | 27 +++ scripts/md2html/gist.css | 71 ++++++ scripts/md2html/md2html.js | 310 ++++++++++++++++++++++++++ scripts/md2html/style-finish.html | 1 + scripts/md2html/style-start.html | 5 + scripts/md2html/syntax-github.css | 99 ++++++++ 11 files changed, 586 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/respec.yaml create mode 100644 scripts/md2html/.gitignore create mode 100644 scripts/md2html/analytics/google.html create mode 100755 scripts/md2html/build.sh create mode 100644 scripts/md2html/gist.css create mode 100644 scripts/md2html/md2html.js create mode 100644 scripts/md2html/style-finish.html create mode 100644 scripts/md2html/style-start.html create mode 100644 scripts/md2html/syntax-github.css diff --git a/.github/workflows/respec.yaml b/.github/workflows/respec.yaml new file mode 100644 index 0000000000..bfa286f72e --- /dev/null +++ b/.github/workflows/respec.yaml @@ -0,0 +1,55 @@ +name: respec + +# author: @MikeRalphson +# issue: https://github.com/OAI/OpenAPI-Specification/issues/1564 + +# +# This workflow updates the respec 'pretty' rendered versions of the spec +# on the gh-pages branch when the corresponding markdown files change. +# + +# run this on push to main +on: + push: + branches: + - main + workflow_dispatch: {} + +jobs: + respec: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 # checkout main branch + + - name: Install dependencies + run: npm i + + - uses: actions/checkout@v2 # checkout gh-pages branch + with: + ref: gh-pages + path: deploy + + - name: run main script + run: scripts/md2html/build.sh + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: update-respec-version + base: gh-pages + delete-branch: true + path: deploy + labels: Housekeeping + reviewers: webron,darrelmiller + title: Update ReSpec versions + commit-message: Update ReSpec versions + signoff: true + body: | + This pull request is automatically triggered by GitHub action `respec`. + + The versions/v*.md files have changed, so the HTML files are automatically being regenerated. + + diff --git a/.gitignore b/.gitignore index aa8e47b4c6..9ffeae3497 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,6 @@ target atlassian-ide-plugin.xml node_modules/ package-lock.json +deploy/ +history Gemfile.lock diff --git a/package.json b/package.json index 59851cb7dc..ac2cac61d3 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,12 @@ "README.md", "schemas/*" ], - "dependencies": {}, + "dependencies": { + "cheerio": "^1.0.0-rc.5", + "highlight.js": "^10.6.0", + "markdown-it": "^12.0.4", + "yargs": "^12.0.5" + }, "devDependencies": { "@hyperjump/json-schema": "^0.17.0", "chai": "^4.3.1", diff --git a/scripts/md2html/.gitignore b/scripts/md2html/.gitignore new file mode 100644 index 0000000000..12516577e2 --- /dev/null +++ b/scripts/md2html/.gitignore @@ -0,0 +1,2 @@ +*.err +input.bs diff --git a/scripts/md2html/analytics/google.html b/scripts/md2html/analytics/google.html new file mode 100644 index 0000000000..dce8d08cf4 --- /dev/null +++ b/scripts/md2html/analytics/google.html @@ -0,0 +1,8 @@ + + + diff --git a/scripts/md2html/build.sh b/scripts/md2html/build.sh new file mode 100755 index 0000000000..3ddf387c2e --- /dev/null +++ b/scripts/md2html/build.sh @@ -0,0 +1,27 @@ +#!/bin/sh + +# run this script from the root of the repo + +mkdir -p deploy/oas +mkdir -p deploy/js + +cd scripts/md2html +mkdir -p history +git show c740e950d:MAINTAINERS.md > history/MAINTAINERS_v2.0.md +cp -p js/* ../../deploy/js 2> /dev/null +cp -p markdown/* ../../deploy/ 2> /dev/null + +node md2html.js --respec --maintainers ./history/MAINTAINERS_v2.0.md ../../versions/2.0.md > ../../deploy/oas/v2.0.html + +latest=`git describe --abbrev=0 --tags` +for filename in ../../versions/[3456789].*.md ; do + version=$(basename "$filename" .md) + node md2html.js --respec --maintainers ../../MAINTAINERS.md ${filename} > ../../deploy/oas/v$version.html + if [ $version = $latest ]; then + if [[ ${version} != *"rc"* ]];then + # version is not a Release Candidate + cp -p ../../deploy/oas/v$version.html ../../deploy/oas/latest.html + fi + fi +done + diff --git a/scripts/md2html/gist.css b/scripts/md2html/gist.css new file mode 100644 index 0000000000..155f0b9160 --- /dev/null +++ b/scripts/md2html/gist.css @@ -0,0 +1,71 @@ +/** + * GitHub Gist Theme + * Author : Louis Barranqueiro - https://github.com/LouisBarranqueiro + */ + +.hljs { + display: block; + background: white; + padding: 0.5em; + color: #333333; + overflow-x: auto; +} + +.hljs-comment, +.hljs-meta { + color: #969896; +} + +.hljs-string, +.hljs-variable, +.hljs-template-variable, +.hljs-strong, +.hljs-emphasis, +.hljs-quote { + color: #df5000; +} + +.hljs-keyword, +.hljs-selector-tag, +.hljs-type { + color: #a71d5d; +} + +.hljs-literal, +.hljs-symbol, +.hljs-bullet, +.hljs-attribute { + color: #0086b3; +} + +.hljs-section, +.hljs-name { + color: #63a35c; +} + +.hljs-tag { + color: #333333; +} + +.hljs-title, +.hljs-attr, +.hljs-selector-id, +.hljs-selector-class, +.hljs-selector-attr, +.hljs-selector-pseudo { + color: #795da3; +} + +.hljs-addition { + color: #55a532; + background-color: #eaffea; +} + +.hljs-deletion { + color: #bd2c00; + background-color: #ffecec; +} + +.hljs-link { + text-decoration: underline; +} diff --git a/scripts/md2html/md2html.js b/scripts/md2html/md2html.js new file mode 100644 index 0000000000..26448d1081 --- /dev/null +++ b/scripts/md2html/md2html.js @@ -0,0 +1,310 @@ +/* bikeshed claims to support markdown syntax, but not (yet) commonmark. +ReSpec supports markdown formatting, but this shows up on the page before being rendered +Hence we render the markdown to HTML ourselves, this gives us +complete control over formatting and syntax highlighting (where +highlight.js does a better job than bikeshed's Pygments) */ + +'use strict'; + +/** +@author Mike Ralphson +**/ + +const fs = require('fs'); +const path = require('path'); +const url = require('url'); +const util = require('util'); + +const hljs = require('highlight.js'); +const cheerio = require('cheerio'); + +let argv = require('yargs') + .boolean('bikeshed') + .alias('b','bikeshed') + .describe('bikeshed','Output in bikeshed format') + .boolean('respec') + .alias('r','respec') + .describe('respec','Output in respec format') + .default('respec',true) + .string('maintainers') + .alias('m','maintainers') + .describe('maintainers','path to MAINTAINERS.md') + .require(1) + .argv; +let maintainers = []; +let emeritus = []; + +const md = require('markdown-it')({ + html: true, + linkify: true, + typographer: true, + highlight: function (str, lang) { + if (lang && hljs.getLanguage(lang)) { // && !argv.respec) { + try { + return '
' +
+                  hljs.highlight(str, { language: lang }).value +
+                  '
'; + } catch (__) { } + } + + return '
' + md.utils.escapeHtml(str) + '
'; + } +}); + +function preface(title,options) { + const respec = { + specStatus: "base", + editors: maintainers, + formerEditors: emeritus, + publishDate: options.publishDate, + subtitle: 'Version '+options.subtitle, + processVersion: 2017, + edDraftURI: "https://github.com/OAI/OpenAPI-Specification/", + github: { + repoURL: "https://github.com/OAI/OpenAPI-Specification/", + branch: "master" + }, + shortName: "OAS", + noTOC: false, + lint: false, + additionalCopyrightHolders: "the Linux Foundation", + includePermalinks: true + }; + + let preface = `${md.utils.escapeHtml(title)}`; + if (options.respec) { + preface += ''; + preface += ``; + preface += fs.readFileSync('./analytics/google.html','utf8'); + preface += ''; + preface += ''; + preface += '
'; + preface += 'The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST 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.'; + preface += '
'; + preface += '
'; + preface += '

Status of This Document

'; + preface += 'The source-of-truth for the specification is the GitHub markdown file referenced above.'; + preface += '
'; + } + else { + preface += ''; + } + return preface; +} + +function doMaintainers() { + let m = fs.readFileSync(argv.maintainers,'utf8'); + let h = md.render(m); + let $ = cheerio.load(h); + let u = $('ul').first(); + $(u).children('li').each(function(e){ + let t = $(this).text().split('@')[0]; + maintainers.push({name:t}); + }); + u = $('ul').eq(1); + $(u).children('li').each(function(e){ + let t = $(this).text().split('@')[0]; + emeritus.push({name:t}); + }); +} + +function getPublishDate(m) { + let h = md.render(m); + let $ = cheerio.load(h); + let t = $('tbody').last(); + let c = $(t).children('tr').children('td'); + let v = $(c[0]).text(); + let d = $(c[1]).text(); + argv.subtitle = v; + if (d === 'TBA') return new Date(); + return new Date(d); +} + +if (argv.maintainers) { + doMaintainers(); +} + +let s = fs.readFileSync(argv._[0],'utf8'); + +if (argv.respec) { + argv.publishDate = getPublishDate(s); +} + +let lines = s.split('\r').join().split('\n'); + +let prevHeading = 0; +let lastIndent = 0; +let inTOC = false; +let inDefs = false; +let inCodeBlock = false; +let bsFix = true; + +let indents = [0]; + +// process the markdown +for (let l in lines) { + let line = lines[l]; + + if (line.startsWith('## Table of Contents')) inTOC = true; + if (line.startsWith('