From 3f97cf958a0edba54ac72f05a33de0b03d82568a Mon Sep 17 00:00:00 2001 From: Ron Date: Tue, 16 Feb 2021 12:30:29 -0700 Subject: [PATCH] 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